include/message-port.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18
  19 #ifndef __APPFW_MESSAGE_PORT_H__
  20 #define __APPFW_MESSAGE_PORT_H__
  21
  22 #include <bundle.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * @brief Enumerations of error code for Application.
  30  */
  31 typedef enum
  32 {
  33         MESSAGEPORT_ERROR_NONE = 0, /**< Successful */
  34         MESSAGEPORT_ERROR_IO_ERROR = -1,                /**< Internal I/O error */
  35         MESSAGEPORT_ERROR_OUT_OF_MEMORY = -2,           /**< Out of memory */
  36         MESSAGEPORT_ERROR_INVALID_PARAMETER = -3,       /**< Invalid parameter */
  37         MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND = -4,           /**< The message port of the remote application is not found */
  38         MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH = -5,   /**< The remote application is not signed with the same certificate */
  39         MESSAGEPORT_ERROR_MAX_EXCEEDED = -6,    /**< The size of message has exceeded the maximum limit */
  40 } messageport_error_e;
  41
  42
  43 /**
  44  * @brief   Called when a message is received from the remote application.
  45  *
  46  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
  47  * @param [in] remote_app_id The ID of the remote application which has sent this message
  48  * @param [in] remote_port The name of the remote message port
  49  * @param [in] trusted_message @c true if the trusted remote message port is ready to receive the response data
  50  * @param [in] data the data passed from the remote application
  51  * @remarks @a data must be released with bundle_free() by you
  52  * @remark @a remote_app_id and @a remote_port will be set if the remote application sends a bidirectional message, otherwise they are NULL.
  53  */
  54 typedef void (*messageport_message_cb)(int id, const char* remote_app_id, const char* remote_port, bool trusted_message, bundle* data);
  55
  56
  57 /**
  58  * @brief Registers the local message port.
  59  *
  60  * @param [in] local_port the name of the local message port
  61  * @param [in] callback The callback function to be called when a message is received
  62  * @return A message port id on success, otherwise a negative error value.
  63  * @retval #MESSAGEPORT_ERROR_NONE Successful
  64  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
  65  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
  66  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
  67  */
  68 int messageport_register_local_port(const char* local_port, messageport_message_cb callback);
  69
  70 /**
  71  * @brief Registers the trusted local message port. @n
  72  *  This allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
  73  *
  74  * @param [in] local_port the name of the local message port
  75  * @param [in] callback The callback function to be called when a message is received
  76  * @return A message port id on success, otherwise a negative error value.
  77  * @retval #MESSAGEPORT_ERROR_NONE Successful
  78  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
  79  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
  80  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
  81  */
  82 int messageport_register_trusted_local_port(const char* local_port, messageport_message_cb callback);
  83
  84 /**
  85  * @brief Checks if the message port of a remote application is registered.
  86  *
  87  * @param [in] remote_app_id The ID of the remote application
  88  * @param [in] remote_port the name of the remote message port
  89  * @param [out] exist @c true if the message port of the remote application exists, otherwise @c false
  90  * @return 0 on success, otherwise a negative error value.
  91  * @retval #MESSAGEPORT_ERROR_NONE Successful
  92  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
  93  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
  94  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
  95  */
  96 int messageport_check_remote_port(const char* remote_app_id, const char *remote_port, bool* exist);
  97
  98 /**
  99  * @brief Checks if the trusted message port of a remote application is registered.
 100  *
 101  * @param [in] remote_app_id The ID of the remote application
 102  * @param [in] remote_port the name of the remote message port
 103  * @param [out] exist @c true if the message port of the remote application exists, otherwise @c false
 104  * @return 0 on success, otherwise a negative error value.
 105  * @retval #MESSAGEPORT_ERROR_NONE Successful
 106  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 107  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 108  * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 109  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 110  */
 111 int messageport_check_trusted_remote_port(const char* remote_app_id, const char *remote_port, bool* exist);
 112
 113 /**
 114  * @brief Sends a message to the message port of a remote application.
 115  *
 116  * @param [in] remote_app_id The ID of the remote application
 117  * @param [in] remote_port the name of the remote message port
 118  * @param [in] message the message to be passed to the remote application, the recommended message size is under 4KB
 119  * @return 0 on success, otherwise a negative error value.
 120  * @retval #MESSAGEPORT_ERROR_NONE Successful
 121  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 122  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 123  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 124  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 125  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 126  *
 127  * @code
 128  * #include <message-port.h>
 129  *
 130  * bundle *b = bundle_create();
 131  * bundle_add(b, "key1", "value1");
 132  * bundle_add(b, "key2", "value2");
 133  *
 134  * int ret = messageport_send_message("0123456789.BasicApp", "BasicAppPort", b);
 135  *
 136  * bundle_free(b);
 137  * @endcode
 138  */
 139 int messageport_send_message(const char* remote_app_id, const char* remote_port, bundle* message);
 140
 141 /**
 142  * @brief Sends a trusted message to the message port of a remote application. @n
 143  *  This allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
 144  *
 145  * @param [in] remote_app_id The ID of the remote application
 146  * @param [in] remote_port the name of the remote message port
 147  * @param [in] message the message to be passed to the remote application, the recommended message size is under 4KB
 148  * @return 0 on success, otherwise a negative error value.
 149  * @retval #MESSAGEPORT_ERROR_NONE Successful
 150  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 151  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 152  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 153  * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 154  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 155  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 156  */
 157 int messageport_send_trusted_message(const char* remote_app_id, const char* remote_port, bundle* message);
 158
 159 /**
 160  * @brief Sends a message to the message port of a remote application. This method is used for the bidirectional communication.
 161  *
 162  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 163  * @param [in] remote_app_id The ID of the remote application
 164  * @param [in] remote_port the name of the remote message port
 165  * @param [in] message the message to be passed to the remote application, the recommended message size is under 4KB
 166  * @return 0 on success, otherwise a negative error value.
 167  * @retval #MESSAGEPORT_ERROR_NONE Successful
 168  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 169  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 170  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 171  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 172  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 173  *
 174  * @code
 175  * #include <message-port.h>
 176  *
 177  * static void
 178  * OnMessageReceived(int id, const char* remote_app_id, const char* remote_port, bool trusted_port, bundle* data)
 179  * {
 180  * }
 181  *
 182  * int main(int argc, char *argv[])
 183  * {
 184  *   bundle *b = bundle_create();
 185  *   bundle_add(b, "key1", "value1");
 186  *   bundle_add(b, "key2", "value2");
 187  *
 188  *   int id = messageport_register_local_port("HelloPort", OnMessageReceived);
 189  *
 190  *   int ret = messageport_send_bidirectional_message(id, "0123456789.BasicApp", "BasicAppPort", b);
 191  *
 192  *   bundle_free(b);
 193  * }
 194  */
 195 int messageport_send_bidirectional_message(int id, const char* remote_app_id, const char* remote_port, bundle* data);
 196
 197 /**
 198  * @brief Sends a trusted message to the message port of a remote application. This method is used for the bidirectional communication.
 199  *  This allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
 200  *
 201  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 202  * @param [in] remote_app_id The ID of the remote application
 203  * @param [in] remote_port the name of the remote message port
 204  * @param [in] message the message to be passed to the remote application, the recommended message size is under 4KB
 205  * @return 0 on success, otherwise a negative error value.
 206  * @retval #MESSAGEPORT_ERROR_NONE Successful
 207  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 208  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 209  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 210  * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 211  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 212  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 213  */
 214 int messageport_send_bidirectional_trusted_message(int id, const char* remote_app_id, const char* remote_port, bundle* data);
 215
 216
 217 /**
 218  * @brief Gets the name of the local message port.
 219  *
 220  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 221  * @param [out] name The name of the local message port
 222  * @return 0 on success, otherwise a negative error value.
 223  * @retval #MESSAGEPORT_ERROR_NONE Successful
 224  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 225  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 226  * @remarks @a name must be released with free() by you
 227  */
 228 int messageport_get_local_port_name(int id, char **name);
 229
 230 /**
 231  * @brief Checks if the local message port is trusted.
 232  *
 233  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 234  * @param [out] @c true if the local message port is trusted
 235  * @return 0 on success, otherwise a negative error value.
 236  * @retval #MESSAGEPORT_ERROR_NONE Successful
 237  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 238  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 239  */
 240 int messageport_check_trusted_local_port(int id, bool *trusted);
 241
 242 /**
 243  * @}
 244  */
 245
 246 #ifdef __cplusplus
 247 }
 248 #endif
 249
 250 #endif /* __APPFW_MESSAGE_PORT_H__ */