Add new apis to watch that remote port is registered and unregistered

[platform/core/appfw/message-port.git] / include / message_port.h

diff --git a/include/message_port.h b/include/message_port.h
index 133dd11..59c8332 100755 (executable)
--- a/include/message_port.h
+++ b/include/message_port.h
@@ -102,6 +102,30 @@ typedef void (*message_port_trusted_message_cb)(int trusted_local_port_id, const
 
 
 /**
+ * @brief Called when a remote port is registered or unregistered.
+ * @details The function is called when a remote port is registered or unregistered
+ *          from the remote application.
+ * @since_tizen 4.0
+ * @remarks @a remote_app_id and @a remote_port can be used until
+ *             message_port_remove_registration_event_cb() is called for the watcher which reported
+ *             the event.
+ * @param[in] remote_app_id        The ID of the remote application that sent this message
+ * @param[in] remote_port          The name of the remote message port
+ * @param[in] trusted_remote_port  Indicates whether remote port is trusted
+ * @param[in] user_data            The user data passed from the register function
+ * @pre Called when a remote port is registered or unregistered if you add it using
+ *      message_port_add_registered_cb() or message_port_add_unregistered_cb() respectively.
+ * @see message_port_add_registered_cb()
+ * @see message_port_add_unregistered_cb()
+ * @see message_port_remove_registration_event_cb()
+ */
+typedef void (*message_port_registration_event_cb)(const char *remote_app_id,
+                                                  const char *remote_port,
+                                                  bool trusted_remote_port,
+                                                  void *user_data);
+
+
+/**
  * @brief Registers the local message port.
  * @details If the message port name is already registered, the previous local message port ID returns and the callback function is changed. \n
  *                     Multiple message ports can be registered.
@@ -346,6 +370,86 @@ EXPORT_API int message_port_send_trusted_message_with_local_port(const char *rem
 
 
 /**
+ * @brief Adds a callback called when a remote port is registered.
+ * @details When remote port is registered, @a registered_cb function is called.
+ *          Each added callback has its own separate watcher.
+ * @since_tizen 4.0
+ * @remarks The specified callback is called only in the main thread.
+ * @param[in] remote_app_id        The ID of the remote application
+ * @param[in] remote_port          The name of the remote message port
+ * @param[in] trusted_remote_port  Indicates whether remote port is trusted
+ * @param[in] registered_cb        The callback function to be called
+ *                                 when remote port is registered
+ * @param[in] user_data            The user data to be passed to the callback function
+ * @param[out] watcher_id          The ID of the watcher which is monitoring the remote port
+ *                                 registration events
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER  The specified @a remote_app_id or @a remote_port
+ *                                               or @a registered_cb is NULL
+ * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY     Out of memory
+ * @retval #MESSAGE_PORT_ERROR_IO_ERROR          Internal I/O error
+ * @see message_port_registration_event_cb()
+ * @see message_port_add_unregistered_cb()
+ * @see message_port_remove_registration_event_cb()
+ */
+EXPORT_API int message_port_add_registered_cb(const char *remote_app_id,
+                                  const char *remote_port,
+                                  bool trusted_remote_port,
+                                  message_port_registration_event_cb registered_cb,
+                                  void *user_data,
+                                  int *watcher_id);
+
+/**
+ * @brief Adds a callback called when a remote port is unregistered.
+ * @details When the remote port is unregistered, @a unregistered_cb function is called.
+ *          Each added callback has its own separate watcher.
+ * @remarks The specified callback is called only in the main thread.
+ * @since_tizen 4.0
+ * @param[in] remote_app_id        The ID of the remote application
+ * @param[in] remote_port          The name of the remote message port
+ * @param[in] trusted_remote_port  Indicates whether remote port is trusted
+ * @param[in] unregistered_cb      The callback function to be called
+ *                                 when remote port is unregistered
+ * @param[in] user_data            The user data to be passed to the callback function
+ * @param[out] watcher_id          The ID of the watcher which is monitoring the remote port
+ *                                 unregistration events
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER  The specified @a remote_app_id or @a remote_port
+ *                                               or @a unregistered_cb is NULL
+ * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY     Out of memory
+ * @retval #MESSAGE_PORT_ERROR_IO_ERROR          Internal I/O error
+ * @see message_port_registration_event_cb()
+ * @see message_port_add_registered_cb()
+ * @see message_port_remove_registration_event_cb()
+ */
+EXPORT_API int message_port_add_unregistered_cb(const char *remote_app_id,
+                                    const char *remote_port,
+                                    bool trusted_remote_port,
+                                    message_port_registration_event_cb unregistered_cb,
+                                    void *user_data,
+                                    int *watcher_id);
+
+
+/**
+ * @brief Removes the registration/unregistration callback associated with the given watcher.
+ * @since_tizen 4.0
+ * @param[in] watcher_id  The ID of watcher which is monitoring remote port
+ *                        registration/unregistration events
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER  The specified @a watcher_id is not correct
+ * @retval #MESSAGE_PORT_ERROR_IO_ERROR           Internal I/O error
+ * @see message_port_registration_event_cb()
+ * @see message_port_add_registered_cb()
+ * @see message_port_add_unregistered_cb()
+ */
+EXPORT_API int message_port_remove_registration_event_cb(int watcher_id);
+
+
+
+/**
  * @}
  */