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 #include <message_port_error.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @brief   Called when a message is received from the remote application.
  31  *
  32  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
  33  * @param [in] remote_app_id The ID of the remote application which has sent this message
  34  * @param [in] remote_port The name of the remote message port
  35  * @param [in] trusted_message @c true if the trusted remote message port is ready to receive the response data
  36  * @param [in] data the data passed from the remote application
  37  * @remarks @a data must be released with bundle_free() by you
  38  * @remark @a remote_app_id and @a remote_port will be set if the remote application sends a bidirectional message, otherwise they are NULL.
  39  */
  40 typedef void (*messageport_message_cb)(int id, const char *remote_app_id, const char *remote_port, bool trusted_message, bundle *data, void *user_data);
  41
  42 /**
  43  * @brief Called when a remote port is registered or unregistered.
  44  * @details The function is called when a remote port is registered or unregistered
  45  *          from the remote application.
  46  * @remarks @a remote_app_id and @a remote_port can be used until
  47  *          messageport_remove_registration_event_cb() is called for the watcher which reported the event.
  48  * @param[in] remote_app_id        The ID of the remote application that sent this message
  49  * @param[in] remote_port          The name of the remote message port
  50  * @param[in] trusted_remote_port  Indicates whether remote port is trusted
  51  * @param[in] user_data            The user data passed from the register function
  52  * @pre Called when a remote port is registered or unregistered if you add it using
  53  *      messageport_add_registered_cb() or messageport_add_unregistered_cb() respectively.
  54  * @see messageport_add_registered_cb()
  55  * @see messageport_add_unregistered_cb()
  56  * @see messageport_remove_registration_event_cb()
  57  */
  58 typedef void (*messageport_registration_event_cb)(const char *remote_app_id,
  59                                                   const char *remote_port,
  60                                                   bool trusted_remote_port,
  61                                                   void *user_data);
  62
  63 /**
  64  * @brief Unregisters the local message port. @n
  65  *
  66  * @param [in] local_port_id the id of the local message port
  67  * @param [in] trusted_port true if target port is trusted port
  68  * @return Return positive on success, otherwise a negative error value.
  69  * @retval #MESSAGEPORT_ERROR_NONE Successful
  70  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
  71  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
  72  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
  73  */
  74  int messageport_unregister_local_port(int local_port_id, bool trusted_port);
  75
  76 /**
  77  * @brief Registers the local message port. @n
  78  * If the message port name is already registered, the previous message port id returns and the callback function is changed.
  79  *
  80  * @param [in] local_port the name of the local message port
  81  * @param [in] callback The callback function to be called when a message is received
  82  * @return A message port id on success, otherwise a negative error value.
  83  * @retval #MESSAGEPORT_ERROR_NONE Successful
  84  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
  85  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
  86  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
  87  * @retval #MESSAGEPORT_ERROR_RESOURCE_UNAVAILABLE Resource temporarily unavailable
  88  */
  89  int messageport_register_local_port(const char *local_port, messageport_message_cb callback);
  90
  91 /**
  92  * @brief Registers the trusted local message port. @n
  93  * If the message port name is already registered, the previous message port id returns and the callback function is changed. @n
  94  * This allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
  95  *
  96  * @param [in] local_port the name of the local message port
  97  * @param [in] callback The callback function to be called when a message is received
  98  * @return A message port id on success, otherwise a negative error value.
  99  * @retval #MESSAGEPORT_ERROR_NONE Successful
 100  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 101  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 102  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 103  * @retval #MESSAGEPORT_ERROR_RESOURCE_UNAVAILABLE Resource temporarily unavailable
 104  */
 105  int messageport_register_trusted_local_port(const char *local_port, messageport_message_cb callback);
 106
 107 /**
 108  * @brief Checks if the message port of a remote application is registered.
 109  *
 110  * @param [in] remote_app_id The ID of the remote application
 111  * @param [in] remote_port the name of the remote message port
 112  * @param [out] exist @c true if the message port of the remote application exists, otherwise @c false
 113  * @return 0 on success, otherwise a negative error value.
 114  * @retval #MESSAGEPORT_ERROR_NONE Successful
 115  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 116  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 117  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 118  * @retval #MESSAGEPORT_ERROR_RESOURCE_UNAVAILABLE Resource temporarily unavailable
 119  */
 120  int messageport_check_remote_port(const char *remote_app_id, const char *remote_port, bool *exist);
 121
 122 /**
 123  * @brief Checks if the trusted message port of a remote application is registered.
 124  *
 125  * @param [in] remote_app_id The ID of the remote application
 126  * @param [in] remote_port the name of the remote message port
 127  * @param [out] exist @c true if the message port of the remote application exists, otherwise @c false
 128  * @return 0 on success, otherwise a negative error value.
 129  * @retval #MESSAGEPORT_ERROR_NONE Successful
 130  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 131  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 132  * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 133  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 134  * @retval #MESSAGEPORT_ERROR_RESOURCE_UNAVAILABLE Resource temporarily unavailable
 135  */
 136  int messageport_check_trusted_remote_port(const char *remote_app_id, const char *remote_port, bool *exist);
 137
 138 /**
 139  * @brief Sends a message to the message port of a remote application.
 140  *
 141  * @param [in] remote_app_id The ID of the remote application
 142  * @param [in] remote_port the name of the remote message port
 143  * @param [in] message the message to be passed to the remote application, the recommended message size is under 4KB
 144  * @return 0 on success, otherwise a negative error value.
 145  * @retval #MESSAGEPORT_ERROR_NONE Successful
 146  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 147  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 148  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 149  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 150  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 151  * @retval #MESSAGEPORT_ERROR_RESOURCE_UNAVAILABLE Resource temporarily unavailable
 152  *
 153  * @code
 154  * #include <message-port.h>
 155  *
 156  * bundle *b = bundle_create();
 157  * bundle_add(b, "key1", "value1");
 158  * bundle_add(b, "key2", "value2");
 159  *
 160  * int ret = messageport_send_message("0123456789.BasicApp", "BasicAppPort", b);
 161  *
 162  * bundle_free(b);
 163  * @endcode
 164  */
 165  int messageport_send_message(const char *remote_app_id, const char *remote_port, bundle *message);
 166
 167 /**
 168  * @brief Sends a trusted message to the message port of a remote application. @n
 169  *  This allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
 170  *
 171  * @param [in] remote_app_id The ID of the remote application
 172  * @param [in] remote_port the name of the remote message port
 173  * @param [in] message the message to be passed to the remote application, the recommended message size is under 4KB
 174  * @return 0 on success, otherwise a negative error value.
 175  * @retval #MESSAGEPORT_ERROR_NONE Successful
 176  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 177  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 178  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 179  * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 180  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 181  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 182  * @retval #MESSAGEPORT_ERROR_RESOURCE_UNAVAILABLE Resource temporarily unavailable
 183  */
 184  int messageport_send_trusted_message(const char *remote_app_id, const char *remote_port, bundle *message);
 185
 186 /**
 187  * @brief Sends a message to the message port of a remote application. This method is used for the bidirectional communication.
 188  *
 189  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 190  * @param [in] remote_app_id The ID of the remote application
 191  * @param [in] remote_port the name of the remote message port
 192  * @param [in] message the message to be passed to the remote application, the recommended message size is under 4KB
 193  * @return 0 on success, otherwise a negative error value.
 194  * @retval #MESSAGEPORT_ERROR_NONE Successful
 195  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 196  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 197  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 198  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 199  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 200  * @retval #MESSAGEPORT_ERROR_RESOURCE_UNAVAILABLE Resource temporarily unavailable
 201  *
 202  * @code
 203  * #include <message-port.h>
 204  *
 205  * static void
 206  * OnMessageReceived(int id, const char* remote_app_id, const char* remote_port, bool trusted_port, bundle* data)
 207  * {
 208  * }
 209  *
 210  * int main(int argc, char *argv[])
 211  * {
 212  *   bundle *b = bundle_create();
 213  *   bundle_add(b, "key1", "value1");
 214  *   bundle_add(b, "key2", "value2");
 215  *
 216  *   int id = messageport_register_local_port("HelloPort", OnMessageReceived);
 217  *
 218  *   int ret = messageport_send_bidirectional_message(id, "0123456789.BasicApp", "BasicAppPort", b);
 219  *
 220  *   bundle_free(b);
 221  * }
 222  */
 223  int messageport_send_bidirectional_message(int id, const char *remote_app_id, const char *remote_port, bundle *data);
 224
 225 /**
 226  * @brief Sends a trusted message to the message port of a remote application. This method is used for the bidirectional communication.
 227  *  This allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
 228  *
 229  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 230  * @param [in] remote_app_id The ID of the remote application
 231  * @param [in] remote_port the name of the remote message port
 232  * @param [in] message the message to be passed to the remote application, the recommended message size is under 4KB
 233  * @return 0 on success, otherwise a negative error value.
 234  * @retval #MESSAGEPORT_ERROR_NONE Successful
 235  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 236  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 237  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 238  * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 239  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 240  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 241  * @retval #MESSAGEPORT_ERROR_RESOURCE_UNAVAILABLE Resource temporarily unavailable
 242  */
 243  int messageport_send_bidirectional_trusted_message(int id, const char *remote_app_id, const char *remote_port, bundle *data);
 244
 245 /**
 246  * @brief Adds a callback called when a remote port is registered.
 247  * @details When remote port is registered, @a registered_cb function is called.
 248  *          Each added callback has its own separate watcher.
 249  * @remarks The specified callback is called only in the main thread.
 250  * @param[in] remote_app_id        The ID of the remote application
 251  * @param[in] remote_port          The name of the remote message port
 252  * @param[in] trusted_remote_port  Indicates whether remote port is trusted
 253  * @param[in] registered_cb        The callback function to be called
 254  *                                 when remote port is registered
 255  * @param[in] user_data            The user data to be passed to the callback function
 256  * @param[out] watcher_id          The ID of the watcher which is monitoring the remote port
 257  *                                 registration events
 258  * @return @c 0 on success,
 259  *         otherwise a negative error value
 260  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER  The specified @a remote_app_id or @a remote_port
 261  *                                               or @a registered_cb is NULL
 262  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY     Out of memory
 263  * @retval #MESSAGE_PORT_ERROR_IO_ERROR          Internal I/O error
 264  * @see messageport_registration_event_cb()
 265  * @see messageport_add_unregistered_cb()
 266  * @see messageport_remove_registration_event_cb()
 267  */
 268 int messageport_add_registered_cb(const char *remote_app_id,
 269                                 const char *remote_port,
 270                                 bool trusted_remote_port,
 271                                 messageport_registration_event_cb registered_cb,
 272                                 void *user_data,
 273                                 int *watcher_id);
 274
 275 /**
 276  * @brief Adds a callback called when a remote port is unregistered.
 277  * @details When remote port is unregistered, @a unregistered_cb function is called.
 278  *          Each added callback has its own separate watcher.
 279  * @remarks The specified callback is called only in the main thread.
 280  * @param[in] remote_app_id        The ID of the remote application
 281  * @param[in] remote_port          The name of the remote message port
 282  * @param[in] trusted_remote_port  Indicates whether remote port is trusted
 283  * @param[in] unregistered_cb      The callback function to be called
 284  *                                 when remote port is unregistered
 285  * @param[in] user_data            The user data to be passed to the callback function
 286  * @param[out] watcher_id          The ID of the watcher which is monitoring the remote port
 287  *                                 unregistration events
 288  * @return @c 0 on success,
 289  *         otherwise a negative error value
 290  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER  The specified @a remote_app_id or @a remote_port
 291  *                                               or @a unregistered_cb is NULL
 292  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY     Out of memory
 293  * @retval #MESSAGE_PORT_ERROR_IO_ERROR          Internal I/O error
 294  * @see messageport_registration_event_cb()
 295  * @see messageport_add_registered_cb()
 296  * @see messageport_remove_registration_event_cb()
 297  */
 298 int messageport_add_unregistered_cb(const char *remote_app_id,
 299                                 const char *remote_port,
 300                                 bool trusted_remote_port,
 301                                 messageport_registration_event_cb unregistered_cb,
 302                                 void *user_data,
 303                                 int *watcher_id);
 304
 305
 306
 307 /**
 308  * @brief Removes the registration/unregistration callbacks associated with the given watcher.
 309  * @param[in] watcher_id  The ID of watcher which is monitoring remote port
 310  *                        registration/unregistration events
 311  * @return @c 0 on success,
 312  *         otherwise a negative error value
 313  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER  The specified @a watcher_id is not correct
 314  * @retval #MESSAGE_PORT_ERROR_IO_ERROR           Internal I/O error
 315  * @see messageport_registration_event_cb()
 316  * @see messageport_add_registered_cb()
 317  * @see messageport_add_unregistered_cb()
 318  */
 319 int messageport_remove_registration_event_cb(int watcher_id);
 320
 321
 322 /**
 323  * @}
 324  */
 325
 326 #ifdef __cplusplus
 327 }
 328 #endif
 329
 330 #endif /* __APPFW_MESSAGE_PORT_H__ */