include/message_port.h

   1 /*
   2  * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_APPFW_MESSAGE_PORT_H__
  18 #define __TIZEN_APPFW_MESSAGE_PORT_H__
  19
  20 #ifdef __GNUC__
  21 #ifndef EXPORT_API
  22 #define EXPORT_API __attribute__((visibility("default")))
  23 #endif
  24 #else
  25 #define EXPORT_API
  26 #endif
  27
  28 #include <stdbool.h>
  29 #include <bundle.h>
  30 #include <tizen_error.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /**
  37  * @addtogroup CAPI_MESSAGE_PORT_MODULE
  38  * @{
  39  */
  40
  41
  42 /**
  43  * @brief Enumeration for error codes of a message port.
  44  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  45  */
  46 typedef enum {
  47         MESSAGE_PORT_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  48         MESSAGE_PORT_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< Internal I/O error */
  49         MESSAGE_PORT_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  50         MESSAGE_PORT_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  51         MESSAGE_PORT_ERROR_PORT_NOT_FOUND = TIZEN_ERROR_MESSAGE_PORT | 0x01, /**< The message port of the remote application is not found */
  52         MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH = TIZEN_ERROR_MESSAGE_PORT | 0x02, /**< The remote application is not signed with the same certificate */
  53         MESSAGE_PORT_ERROR_MAX_EXCEEDED = TIZEN_ERROR_MESSAGE_PORT | 0x03, /**< The size of the message has exceeded the maximum limit */
  54         MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLE = TIZEN_ERROR_MESSAGE_PORT | 0x04 /**< Resource is temporarily unavailable */
  55 } message_port_error_e;
  56
  57
  58 /**
  59  * @brief Called when a message is received.
  60  * @details The function is called when a message is received from the remote application.
  61  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  62  * @remarks @a message is automatically freed by framework when callback returned, you can keep @a message using bundle_dup() @n
  63  *          @a remote_port will be set only if the remote application sends a message with its port information using message_port_send_message_with_local_port(), otherwise it is @c NULL @n
  64  *          When message is sent from remote application by message_port_send_message_with_local_port() in bidirectional communication, trusted_remote_port is used to check whether remote port is trusted port or not
  65  *          This callback is called only in the main thread.
  66  * @param[in] local_port_id     The local message port ID returned by message_port_register_local_port()
  67  * @param[in] remote_app_id     The ID of the remote application that sent this message
  68  * @param[in] remote_port The name of the remote message port
  69  * @param[in] trusted_remote_port If @c true, the remote port is a trusted port; otherwise if @c false, it is not
  70  * @param[in] message The message passed from the remote application
  71  * @param[in] user_data The user data passed from the register function
  72  * @pre Either message_port_send_message() or message_port_send_message_with_local_port() from the remote application will invoke this function if you register it using message_port_register_local_port()
  73  * @see message_port_register_local_port()
  74  * @see message_port_unregister_local_port()
  75  * @see message_port_send_message()
  76  * @see message_port_send_message_with_local_port()
  77  */
  78 typedef void (*message_port_message_cb)(int local_port_id, const char *remote_app_id, const char *remote_port, bool trusted_remote_port, bundle *message, void *user_data);
  79
  80
  81 /**
  82  * @brief Called when a trusted message is received.
  83  * @details This function is called when a trusted message is received from the remote application.
  84  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  85  * @remarks You can keep @a message using bundle_dup(). @n
  86  *          @a remote_port will be set only if the remote application sends a message with its port information using message_port_send_trusted_message_with_local_port(), otherwise it is @c NULL. @n
  87  *          When message is sent from remote application by message_port_send_trusted_message_with_local_port() in bidirectional communication, trusted_remote_port is used to check whether remote port is trusted port or not.
  88  *          This callback is called only in the main thread.
  89  * @param[in] trusted_local_port_id     The message port ID returned by message_port_register_trusted_local_port()
  90  * @param[in] remote_app_id     The ID of the remote application that sent this message
  91  * @param[in] remote_port The name of the remote message port
  92  * @param[in] trusted_remote_port If @c true, the remote port is a trusted port; otherwise if @c false, it is not
  93  * @param[in] message The message passed from the remote application
  94  * @param[in] user_data The user data passed from the register function
  95  * @pre Either message_port_send_trusted_message() or message_port_send_trusted_message_with_local_port() from the remote application will invoke this function if you register it using message_port_register_trusted_local_port().
  96  * @see message_port_register_trusted_local_port()
  97  * @see message_port_unregister_trusted_local_port()
  98  * @see message_port_send_trusted_message()
  99  * @see message_port_send_trusted_message_with_local_port()
 100  */
 101 typedef void (*message_port_trusted_message_cb)(int trusted_local_port_id, const char *remote_app_id, const char *remote_port, bool trusted_remote_port, bundle *message, void *user_data);
 102
 103
 104 /**
 105  * @brief Called when a remote port is registered or unregistered.
 106  * @details The function is called when a remote port is registered or unregistered
 107  *          from the remote application.
 108  * @since_tizen 4.0
 109  * @remarks @a remote_app_id and @a remote_port can be used until
 110  *             message_port_remove_registration_event_cb() is called for the watcher which reported
 111  *             the event.
 112  * @param[in] remote_app_id        The ID of the remote application that sent this message
 113  * @param[in] remote_port          The name of the remote message port
 114  * @param[in] trusted_remote_port  Indicates whether remote port is trusted
 115  * @param[in] user_data            The user data passed from the register function
 116  * @pre Called when a remote port is registered or unregistered if you add it using
 117  *      message_port_add_registered_cb() or message_port_add_unregistered_cb() respectively.
 118  * @see message_port_add_registered_cb()
 119  * @see message_port_add_unregistered_cb()
 120  * @see message_port_remove_registration_event_cb()
 121  */
 122 typedef void (*message_port_registration_event_cb)(const char *remote_app_id,
 123                                                         const char *remote_port,
 124                                                         bool trusted_remote_port,
 125                                                         void *user_data);
 126
 127
 128 /**
 129  * @brief Registers the local message port.
 130  * @details If the message port name is already registered, the previous local message port ID returns and the callback function is changed. \n
 131  *                      Multiple message ports can be registered.
 132  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 133  * @remarks The specified callback is called only in the main thread.
 134  * @param[in] local_port The name of the local message port
 135  * @param[in] callback The callback function to be called when a message is received
 136  * @param[in] user_data The user data to be passed to the callback function
 137  * @return A local message port ID on success,
 138  *         otherwise a negative error value
 139  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a local_port or @a callback is NULL
 140  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
 141  * @retval MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
 142  * @see message_port_unregister_local_port()
 143  */
 144 EXPORT_API int message_port_register_local_port(const char *local_port, message_port_message_cb callback, void *user_data);
 145
 146
 147 /**
 148  * @brief Registers the trusted local message port.
 149  * @details If the message port name is already registered, the previous local message port ID returns and the callback function is changed. @n
 150  *          It allows communications only if the applications are signed with the same certificate, which is uniquely assigned to the developer. @n
 151  *          Multiple message ports can be registered.
 152  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 153  * @remarks The specified callback is called only in the main thread.
 154  * @param[in] trusted_local_port The name of the trusted local message port
 155  * @param[in] callback The callback function to be called when a trusted message is received
 156  * @param[in] user_data The user data to be passed to the callback function
 157  * @return A trusted local message port ID on success,
 158  *         otherwise a negative error value
 159  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a trusted_local_port or @a callback is NULL
 160  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
 161  * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
 162  * @see message_port_unregister_trusted_local_port()
 163  */
 164 EXPORT_API int message_port_register_trusted_local_port(const char *trusted_local_port, message_port_trusted_message_cb callback, void *user_data);
 165
 166
 167 /**
 168  * @brief Unregisters the local message port.
 169  * @details This method unregisters the callback function with the specified local port ID.
 170  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 171  * @param[in] local_port_id     The local message port ID
 172  * @return @c 0 on success,
 173  *         otherwise a negative error value
 174  * @retval #MESSAGE_PORT_ERROR_NONE     Successful
 175  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a local_port_id is not positive
 176  * @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The specified @a local_port_id cannot be found
 177  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
 178  * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
 179  * @see message_port_register_local_port()
 180  */
 181 EXPORT_API int message_port_unregister_local_port(int local_port_id);
 182
 183
 184 /**
 185  * @brief Registers the trusted local message port.
 186  * @details This method unregisters the callback function with the specified local port ID. @n
 187  *          It allows communications only if the applications are signed with the same certificate, which is uniquely assigned to the developer.
 188  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 189  * @param[in] trusted_local_port_id     The trusted local message port ID
 190  * @return @c 0 on success,
 191  *         otherwise a negative error value
 192  * @retval #MESSAGE_PORT_ERROR_NONE     Successful
 193  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a trusted_local_port_id is not positive
 194  * @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The specified @a trusted_local_port_id cannot be found
 195  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
 196  * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
 197  * @see message_port_register_trusted_local_port()
 198  */
 199 EXPORT_API int message_port_unregister_trusted_local_port(int trusted_local_port_id);
 200
 201
 202 /**
 203  * @brief Checks whether the message port of a remote application is registered.
 204  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 205  * @remarks If this function returns a negative error value, the out parameter @a exist will not be changed.
 206  * @param[in] remote_app_id The ID of the remote application
 207  * @param[in] remote_port The name of the remote message port
 208  * @param[out] exist If @c true, the message port of the remote application exists;
 209  *                   otherwise @c false
 210  * @return @c 0 on success,
 211  *         otherwise a negative error value
 212  * @retval #MESSAGE_PORT_ERROR_NONE     Successful
 213  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id or @a remote_port is NULL
 214  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
 215  * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
 216  */
 217 EXPORT_API int message_port_check_remote_port(const char *remote_app_id, const char *remote_port, bool *exist);
 218
 219
 220 /**
 221  * @brief Checks whether the trusted message port of a remote application is registered.
 222  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 223  * @remarks     If this function returns a negative error value, the out parameter @a exist will not be changed.
 224  * @param[in] remote_app_id The ID of the remote application
 225  * @param[in] remote_port The name of the remote message port
 226  * @param[out] exist If @c true, the message port of the remote application exists;
 227  *                   otherwise @c false
 228  * @return @c 0 on success,
 229  *         otherwise a negative error value
 230  * @retval #MESSAGE_PORT_ERROR_NONE Successful
 231  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id or @a remote_port is @c NULL
 232  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
 233  * @retval #MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 234  * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
 235  */
 236 EXPORT_API int message_port_check_trusted_remote_port(const char *remote_app_id, const char *remote_port, bool *exist);
 237
 238
 239 /**
 240  * @brief Sends a message to the message port of a remote application.
 241  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 242  * @remarks @a message must be released with bundle_free() after sending the message.
 243  * @param[in] remote_app_id The ID of the remote application
 244  * @param[in] remote_port The name of the remote message port
 245  * @param[in] message The message to be passed to the remote application, the recommended message size is under 4KB
 246  * @return @c 0 on success,
 247  *         otherwise a negative error value
 248  * @retval #MESSAGE_PORT_ERROR_NONE Successful
 249  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id, @a remote_port or @a message is NULL
 250  * @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The message port of the remote application cannot be found
 251  * @retval #MESSAGE_PORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 252  * @retval #MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLE Resource temporarily unavailable
 253  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
 254  * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
 255  * @post It invokes message_port_message_cb() on the remote application.
 256  * @see message_port_message_cb()
 257  * @see message_port_register_local_port()
 258  * @see message_port_unregister_local_port()
 259  *
 260  * @code
 261  * #include <message_port.h>
 262  * bundle *b = bundle_create();
 263  * bundle_add(b, "key1", "value1");
 264  * bundle_add(b, "key2", "value2");
 265  * int ret = message_port_send_message("0123456789.BasicApp", "BasicAppPort", b);
 266  * bundle_free(b);
 267  * @endcode
 268  */
 269 EXPORT_API int message_port_send_message(const char *remote_app_id, const char *remote_port, bundle *message);
 270
 271
 272 /**
 273  * @brief Sends a trusted message to the message port of a remote application.
 274  * @details This method allows communication only if the applications are signed with the same certificate, which is uniquely assigned to the developer.
 275  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 276  * @remarks You must release @a message using bundle_free() after sending the message.
 277  * @param[in] remote_app_id The ID of the remote application
 278  * @param[in] remote_port The name of the remote message port
 279  * @param[in] message The message to be passed to the remote application, the recommended message size is under 4KB
 280  * @return @c 0 on success,
 281  *         otherwise a negative error value
 282  * @retval #MESSAGE_PORT_ERROR_NONE Successful
 283  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id, @a remote_port or @a message is @c NULL
 284  * @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The message port of the remote application cannot be found
 285  * @retval #MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 286  * @retval #MESSAGE_PORT_ERROR_MAX_EXCEEDED The size of the message has exceeded the maximum limit
 287  * @retval #MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLE Resource is temporarily unavailable
 288  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
 289  * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
 290  * @post It invokes message_port_trusted_message_cb() on the remote application.
 291  * @see message_port_trusted_message_cb()
 292  * @see message_port_register_trusted_local_port()
 293  * @see message_port_unregister_trusted_local_port()
 294  */
 295 EXPORT_API int message_port_send_trusted_message(const char *remote_app_id, const char *remote_port, bundle *message);
 296
 297
 298 /**
 299  * @brief Sends a message with local port information to the message port of a remote application.
 300  * @details This method is used for bidirectional communication.
 301  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 302  * @remarks You must release @a message using bundle_free() after sending the message.
 303  * @param[in] remote_app_id The ID of the remote application
 304  * @param[in] remote_port The name of the remote message port
 305  * @param[in] message The message to be passed to the remote application, the recommended message size is under 4KB
 306  * @param[in] local_port_id The message port ID returned by message_port_register_local_port() or message_port_register_trusted_local_port()
 307  * @return @c 0 on success,
 308  *         otherwise a negative error value
 309  * @retval #MESSAGE_PORT_ERROR_NONE Successful
 310  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id, @a remote_port or @a message is @c NULL and
 311  *                                               The specified @a local_port_id is not positive
 312  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
 313  * @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The port of the local or remote application cannot be found
 314  * @retval #MESSAGE_PORT_ERROR_MAX_EXCEEDED The size of the message has exceeded the maximum limit
 315  * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
 316  * @post It invokes message_port_message_cb() on the remote application.
 317  * @see message_port_message_cb()
 318  * @see message_port_register_local_port()
 319  * @see message_port_unregister_local_port()
 320  *
 321  * @code
 322  * #include <message_port.h>
 323  *
 324  * static void message_port_receive_cb(int local_port_id, const char *remote_app_id, const char *remote_port, bundle *message) {}
 325  *
 326  * int
 327  * main(int argc, char *argv[])
 328  * {
 329  *   bundle *b = bundle_create();
 330  *   bundle_add(b, "key1", "value1");
 331  *   bundle_add(b, "key2", "value2");
 332  *
 333  *   int local_port_id = message_port_register_local_port("HelloPort", message_port_receive_cb);
 334  *
 335  *   int ret = message_port_send_message_with_local_port("0123456789.BasicApp", "BasicAppPort", b, local_port_id);
 336  *
 337  *   bundle_free(b);
 338  * }
 339  * @endcode
 340  */
 341 EXPORT_API int message_port_send_message_with_local_port(const char *remote_app_id, const char *remote_port, bundle *message, int local_port_id);
 342
 343
 344 /**
 345  * @brief Sends a trusted message with local port information to the message port of a remote application.
 346  * @details This method is used for bidirectional communication. @n
 347  *          It allows communications only if the applications are signed with the same certificate, which is uniquely assigned to the developer.
 348  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 349  * @remarks You muse release @a message using bundle_free() after sending the message.
 350  * @param[in] remote_app_id The ID of the remote application
 351  * @param[in] remote_port The name of the remote message port
 352  * @param[in] message The message to be passed to the remote application, the recommended message size is under 4KB
 353  * @param[in] local_port_id     The message port ID returned by message_port_register_local_port() or message_port_register_trusted_local_port()
 354  * @return @c 0 on success,
 355  *         otherwise a negative error value
 356  * @retval #MESSAGE_PORT_ERROR_NONE     Successful
 357  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id, @a remote_port or @a message is @c NULL and
 358  *                                               specified @a local_port_id is not positive
 359  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
 360  * @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The port of the local or remote application cannot be found
 361  * @retval #MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 362  * @retval #MESSAGE_PORT_ERROR_MAX_EXCEEDED The size of the message has exceeded the maximum limit
 363  * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
 364  * @post It invokes message_port_trusted_message_cb() on the remote application.
 365  * @see message_port_trusted_message_cb()
 366  * @see message_port_register_trusted_local_port()
 367  * @see message_port_unregister_trusted_local_port()
 368  */
 369 EXPORT_API int message_port_send_trusted_message_with_local_port(const char *remote_app_id, const char *remote_port, bundle *message, int local_port_id);
 370
 371
 372 /**
 373  * @brief Adds a callback called when a remote port is registered.
 374  * @details When remote port is registered, @a registered_cb function is called.
 375  *          Each added callback has its own separate watcher.
 376  * @since_tizen 4.0
 377  * @remarks The specified callback is called only in the main thread.
 378  * @param[in] remote_app_id        The ID of the remote application
 379  * @param[in] remote_port          The name of the remote message port
 380  * @param[in] trusted_remote_port  Indicates whether remote port is trusted
 381  * @param[in] registered_cb        The callback function to be called
 382  *                                 when remote port is registered
 383  * @param[in] user_data            The user data to be passed to the callback function
 384  * @param[out] watcher_id          The ID of the watcher which is monitoring the remote port
 385  *                                 registration events
 386  * @return @c 0 on success,
 387  *         otherwise a negative error value
 388  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER  The specified @a remote_app_id or @a remote_port
 389  *                                               or @a registered_cb is NULL
 390  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY     Out of memory
 391  * @retval #MESSAGE_PORT_ERROR_IO_ERROR          Internal I/O error
 392  * @see message_port_registration_event_cb()
 393  * @see message_port_add_unregistered_cb()
 394  * @see message_port_remove_registration_event_cb()
 395  */
 396 EXPORT_API int message_port_add_registered_cb(const char *remote_app_id,
 397                                                 const char *remote_port,
 398                                                 bool trusted_remote_port,
 399                                                 message_port_registration_event_cb registered_cb,
 400                                                 void *user_data,
 401                                                 int *watcher_id);
 402
 403 /**
 404  * @brief Adds a callback called when a remote port is unregistered.
 405  * @details When the remote port is unregistered, @a unregistered_cb function is called.
 406  *          Each added callback has its own separate watcher.
 407  * @remarks The specified callback is called only in the main thread.
 408  * @since_tizen 4.0
 409  * @param[in] remote_app_id        The ID of the remote application
 410  * @param[in] remote_port          The name of the remote message port
 411  * @param[in] trusted_remote_port  Indicates whether remote port is trusted
 412  * @param[in] unregistered_cb      The callback function to be called
 413  *                                 when remote port is unregistered
 414  * @param[in] user_data            The user data to be passed to the callback function
 415  * @param[out] watcher_id          The ID of the watcher which is monitoring the remote port
 416  *                                 unregistration events
 417  * @return @c 0 on success,
 418  *         otherwise a negative error value
 419  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER  The specified @a remote_app_id or @a remote_port
 420  *                                               or @a unregistered_cb is NULL
 421  * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY     Out of memory
 422  * @retval #MESSAGE_PORT_ERROR_IO_ERROR          Internal I/O error
 423  * @see message_port_registration_event_cb()
 424  * @see message_port_add_registered_cb()
 425  * @see message_port_remove_registration_event_cb()
 426  */
 427 EXPORT_API int message_port_add_unregistered_cb(const char *remote_app_id,
 428                                                 const char *remote_port,
 429                                                 bool trusted_remote_port,
 430                                                 message_port_registration_event_cb unregistered_cb,
 431                                                 void *user_data,
 432                                                 int *watcher_id);
 433
 434
 435 /**
 436  * @brief Removes the registration/unregistration callback associated with the given watcher.
 437  * @since_tizen 4.0
 438  * @param[in] watcher_id  The ID of watcher which is monitoring remote port
 439  *                        registration/unregistration events
 440  * @return @c 0 on success,
 441  *         otherwise a negative error value
 442  * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER  The specified @a watcher_id is not correct
 443  * @retval #MESSAGE_PORT_ERROR_IO_ERROR           Internal I/O error
 444  * @see message_port_registration_event_cb()
 445  * @see message_port_add_registered_cb()
 446  * @see message_port_add_unregistered_cb()
 447  */
 448 EXPORT_API int message_port_remove_registration_event_cb(int watcher_id);
 449
 450
 451
 452 /**
 453  * @}
 454  */
 455
 456 #ifdef __cplusplus
 457 }
 458 #endif
 459
 460 #endif /* __TIZEN_APPFW_MESSAGE_PORT_H__ */