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  * @brief Enumeration for error codes of a message port.
  43  *
  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  * @brief Called when a message is received.
  59  * @details The function is called when a message is received from the remote application.
  60  *
  61  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  62  *
  63  * @remarks              @a message is automatically freed by framework when callback returned, you can keep @a message using bundle_dup(). @n
  64  *                              @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
  65  *                              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.
  66  *                              This callback is called only in the main thread.
  67  *
  68  * @param[in] local_port_id             The local message port ID returned by message_port_register_local_port()
  69  * @param[in] remote_app_id             The ID of the remote application that sent this message
  70  * @param[in] remote_port               The name of the remote message port
  71  * @param[in]   trusted_remote_port             If @c true the remote port is a trusted port, otherwise if @c false it is not
  72  * @param[in] message                   The message passed from the remote application
  73  * @param[in] user_data                 The user data passed from the register function
  74  * @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().
  75  * @see                 message_port_register_local_port()
  76  * @see                 message_port_unregister_local_port()
  77  * @see                 message_port_send_message()
  78  * @see                 message_port_send_message_with_local_port()
  79  */
  80 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);
  81
  82 /**
  83  * @brief Called when a trusted message is received.
  84  * @details This function is called when a trusted message is received from the remote application.
  85  *
  86  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  87  *
  88  * @remarks              You can keep @a message using  bundle_dup(). @n
  89  *                              @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
  90  *                              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.
  91  *                              This callback is called only in the main thread.
  92  * @param[in] trusted_local_port_id             The message port ID returned by message_port_register_trusted_local_port()
  93  * @param[in] remote_app_id                             The ID of the remote application that sent this message
  94  * @param[in] remote_port                               The name of the remote message port
  95  * @param[in]   trusted_remote_port             If @c true the remote port is a trusted port, otherwise if @c false it is not
  96  * @param[in] message                                   The message passed from the remote application
  97  * @param[in] user_data                                 The user data passed from the register function
  98  * @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().
  99  * @see                 message_port_register_trusted_local_port()
 100  * @see                 message_port_unregister_trusted_local_port()
 101  * @see                 message_port_send_trusted_message()
 102  * @see                 message_port_send_trusted_message_with_local_port()
 103  */
 104 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);
 105
 106 /**
 107  * @brief Registers the local message port.
 108  * @details If the message port name is already registered, the previous local message port ID returns and the callback function is changed. \n
 109  *                      Multiple message ports can be registered.
 110  *
 111  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 112  *
 113  * @remarks             The specified callback is called only in the main thread.
 114  * @param[in] local_port        The name of the local message port
 115  * @param[in] callback          The callback function to be called when a message is received
 116  * @param[in] user_data         The user data to be passed to the callback function
 117  *
 118  * @return              A local message port ID on success,
 119  *                              otherwise a negative error value
 120  * @retval              #MESSAGE_PORT_ERROR_INVALID_PARAMETER   The specified @a local_port or @a callback is NULL
 121  * @retval              #MESSAGE_PORT_ERROR_OUT_OF_MEMORY               Out of memory
 122  * @retval              #MESSAGE_PORT_ERROR_IO_ERROR                    Internal I/O error
 123  * @see                 message_port_unregister_local_port()
 124  */
 125 EXPORT_API int message_port_register_local_port(const char *local_port, message_port_message_cb callback, void *user_data);
 126
 127 /**
 128  * @brief               Registers the trusted local message port.
 129  * @details             If the message port name is already registered, the previous local message port ID returns and the callback function is changed. @n
 130  *                              It allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer. @n
 131  *                              Multiple message ports can be registered.
 132  *
 133  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 134  *
 135  * @remarks             The specified callback is called only in the main thread.
 136  * @param[in] trusted_local_port        The name of the trusted local message port
 137  * @param[in] callback          The callback function to be called when a trusted message is received
 138  * @param[in] user_data         The user data to be passed to the callback function
 139  * @return              A trusted local message port ID on success,
 140  *                              otherwise a negative error value
 141  * @retval              #MESSAGE_PORT_ERROR_INVALID_PARAMETER   The specified @a trusted_local_port or @a callback is NULL
 142  * @retval              #MESSAGE_PORT_ERROR_OUT_OF_MEMORY               Out of memory
 143  * @retval              #MESSAGE_PORT_ERROR_IO_ERROR                    Internal I/O error
 144  * @see                 message_port_unregister_trusted_local_port()
 145  */
 146 EXPORT_API int message_port_register_trusted_local_port(const char *trusted_local_port, message_port_trusted_message_cb callback, void *user_data);
 147
 148 /**
 149  * @brief Unregisters the local message port.
 150  * @details This method unregisters the callback function with the specified local port ID.
 151  *
 152  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 153  *
 154  * @param[in] local_port_id             The local message port ID
 155  * @return              0 on success,
 156  *                              otherwise a negative error value
 157  * @retval              #MESSAGE_PORT_ERROR_NONE                                Successful
 158  * @retval              #MESSAGE_PORT_ERROR_INVALID_PARAMETER   The specified @a local_port_id is not positive
 159  * @retval              #MESSAGE_PORT_ERROR_PORT_NOT_FOUND              The specified @a local_port_id cannot be found
 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_register_local_port()
 163  */
 164 EXPORT_API int message_port_unregister_local_port(int local_port_id);
 165
 166 /**
 167  * @brief               Registers the trusted local message port.
 168  * @details             This method unregisters the callback function with the specified local port ID. @n
 169  *                              It allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
 170  *
 171  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 172  *
 173  * @param[in] trusted_local_port_id             The trusted local message port ID
 174  * @return              @c 0 on success,
 175  *                              otherwise a negative error value
 176  * @retval              #MESSAGE_PORT_ERROR_NONE                                Successful
 177  * @retval              #MESSAGE_PORT_ERROR_INVALID_PARAMETER   The specified @a trusted_local_port_id is not positive
 178  * @retval              #MESSAGE_PORT_ERROR_PORT_NOT_FOUND              The specified @a trusted_local_port_id cannot be found
 179  * @retval              #MESSAGE_PORT_ERROR_OUT_OF_MEMORY               Out of memory
 180  * @retval              #MESSAGE_PORT_ERROR_IO_ERROR                    Internal I/O error
 181  * @see                 message_port_register_trusted_local_port()
 182  */
 183 EXPORT_API int message_port_unregister_trusted_local_port(int trusted_local_port_id);
 184
 185 /**
 186  * @brief Checks whether the message port of a remote application is registered.
 187  *
 188  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 189  *
 190  * @remarks             If this function returns a negative error value, the out parameter @a exist will not be changed.
 191  * @param[in]   remote_app_id           The ID of the remote application
 192  * @param[in]   remote_port                     The name of the remote message port
 193  * @param[out]  exist                           If @c true the message port of the remote application exists,
 194  *                                                              otherwise @c false
 195  * @return              @c 0 on success,
 196  *                              otherwise a negative error value
 197  * @retval              #MESSAGE_PORT_ERROR_NONE                                Successful
 198  * @retval              #MESSAGE_PORT_ERROR_INVALID_PARAMETER   The specified @a remote_app_id or @a remote_port is NULL
 199  * @retval              #MESSAGE_PORT_ERROR_OUT_OF_MEMORY               Out of memory
 200  * @retval              #MESSAGE_PORT_ERROR_IO_ERROR Internal   I/O error
 201  */
 202 EXPORT_API int message_port_check_remote_port(const char *remote_app_id, const char *remote_port, bool *exist);
 203
 204 /**
 205  * @brief Checks whether the trusted message port of a remote application is registered.
 206  *
 207  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 208  *
 209  * @remarks             If this function returns a negative error value, the out parameter @a exist will not be changed.
 210  * @param[in]   remote_app_id           The ID of the remote application
 211  * @param[in]   remote_port                     The name of the remote message port
 212  * @param[out]  exist                           If @c true  the message port of the remote application exists,
 213  *                                                              otherwise @c false
 214  * @return              @c 0 on success,
 215  *                              otherwise a negative error value
 216  * @retval              #MESSAGE_PORT_ERROR_NONE                                        Successful
 217  * @retval              #MESSAGE_PORT_ERROR_INVALID_PARAMETER           The specified @a remote_app_id or @a remote_port is @c NULL
 218  * @retval              #MESSAGE_PORT_ERROR_OUT_OF_MEMORY                       Out of memory
 219  * @retval              #MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH       The remote application is not signed with the same certificate
 220  * @retval              #MESSAGE_PORT_ERROR_IO_ERROR                            Internal I/O error
 221  */
 222 EXPORT_API int message_port_check_trusted_remote_port(const char *remote_app_id, const char *remote_port, bool *exist);
 223
 224 /**
 225  * @brief Sends a message to the message port of a remote application.
 226  *
 227  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 228  *
 229  * @remarks     @a message must be released with bundle_free() after sending the message.
 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              #MESSAGE_PORT_ERROR_NONE                                        Successful
 235  * @retval              #MESSAGE_PORT_ERROR_INVALID_PARAMETER           The specified @a remote_app_id, @a remote_port or @a message is NULL
 236  * @retval              #MESSAGE_PORT_ERROR_PORT_NOT_FOUND                      The message port of the remote application cannot be found
 237  * @retval              #MESSAGE_PORT_ERROR_MAX_EXCEEDED                        The size of message has exceeded the maximum limit
 238  * @retval              #MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLE        Resource temporarily unavailable
 239  * @retval              #MESSAGE_PORT_ERROR_OUT_OF_MEMORY                       Out of memory
 240  * @retval              #MESSAGE_PORT_ERROR_IO_ERROR                            Internal I/O error
 241  * @post                It invokes message_port_message_cb() on the remote application.
 242  * @see                 message_port_message_cb()
 243  * @see                 message_port_register_local_port()
 244  * @see                 message_port_unregister_local_port()
 245  *
 246  * @code
 247  * #include <message_port.h>
 248  *
 249  * bundle *b = bundle_create();
 250  * bundle_add(b, "key1", "value1");
 251  * bundle_add(b, "key2", "value2");
 252  *
 253  * int ret = message_port_send_message("0123456789.BasicApp", "BasicAppPort", b);
 254  *
 255  * bundle_free(b);
 256  * @endcode
 257  */
 258 EXPORT_API int message_port_send_message(const char *remote_app_id, const char *remote_port, bundle *message);
 259
 260 /**
 261  * @brief Sends a trusted message to the message port of a remote application.
 262  * @details This method allows communication only if the applications are signed with the same certificate which is uniquely assigned to the developer.
 263  *
 264  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 265  *
 266  * @remarks     You must release @a message using bundle_free() after sending the message.
 267  * @param[in] remote_app_id             The ID of the remote application
 268  * @param[in] remote_port               The name of the remote message port
 269  * @param[in] message                   The message to be passed to the remote application, the recommended message size is under 4KB
 270  * @return              0 on success,
 271  *                              otherwise a negative error value
 272  * @retval              #MESSAGE_PORT_ERROR_NONE                                        Successful
 273  * @retval              #MESSAGE_PORT_ERROR_INVALID_PARAMETER           The specified @a remote_app_id, @a remote_port or @a message is @c NULL
 274  * @retval              #MESSAGE_PORT_ERROR_PORT_NOT_FOUND                      The message port of the remote application cannot be found
 275  * @retval              #MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH       The remote application is not signed with the same certificate
 276  * @retval              #MESSAGE_PORT_ERROR_MAX_EXCEEDED                        The size of the message has exceeded the maximum limit
 277  * @retval              #MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLE        Resource is temporarily unavailable
 278  * @retval              #MESSAGE_PORT_ERROR_OUT_OF_MEMORY                       Out of memory
 279  * @retval              #MESSAGE_PORT_ERROR_IO_ERROR                            Internal I/O error
 280  * @post                It invokes message_port_trusted_message_cb() on the remote application.
 281  * @see                 message_port_trusted_message_cb()
 282  * @see                 message_port_register_trusted_local_port()
 283  * @see                 message_port_unregister_trusted_local_port()
 284  */
 285 EXPORT_API int message_port_send_trusted_message(const char *remote_app_id, const char *remote_port, bundle *message);
 286
 287 /**
 288  * @brief               Sends a message with local port information to the message port of a remote application.
 289  * @details             This method is used for bidirectional communication.
 290  *
 291  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 292  *
 293  * @remarks             You must releas @a message using bundle_free() after sending the message.
 294  * @param[in]   remote_app_id           The ID of the remote application
 295  * @param[in]   remote_port                     The name of the remote message port
 296  * @param[in]   message                         The message to be passed to the remote application, the recommended message size is under 4KB
 297  * @param[in]   local_port_id           The message port ID returned by message_port_register_local_port() or message_port_register_trusted_local_port()
 298  * @return              @c 0 on success,
 299  *                              otherwise a negative error value
 300  * @retval              #MESSAGE_PORT_ERROR_NONE                                        Successful
 301  * @retval              #MESSAGE_PORT_ERROR_INVALID_PARAMETER           The specified @a remote_app_id, @a remote_port or @a message is @c NULL and
 302                                                                                                         The specified @a local_port_id is not positive
 303  * @retval              #MESSAGE_PORT_ERROR_OUT_OF_MEMORY                       Out of memory
 304  * @retval              #MESSAGE_PORT_ERROR_PORT_NOT_FOUND                      The port of the local or remote application cannot be found
 305  * @retval              #MESSAGE_PORT_ERROR_MAX_EXCEEDED                        The size of the message has exceeded the maximum limit
 306  * @retval              #MESSAGE_PORT_ERROR_IO_ERROR                            Internal I/O error
 307  * @post                It invokes message_port_message_cb() on the remote application.
 308  * @see                 message_port_message_cb()
 309  * @see                 message_port_register_local_port()
 310  * @see                 message_port_unregister_local_port()
 311  *
 312  * @code
 313  * #include <message_port.h>
 314  *
 315  * static void
 316  * message_port_receive_cb(int local_port_id, const char *remote_app_id, const char *remote_port, bundle *message)
 317  * {
 318  * }
 319  *
 320  * int main(int argc, char *argv[])
 321  * {
 322  *   bundle *b = bundle_create();
 323  *   bundle_add(b, "key1", "value1");
 324  *   bundle_add(b, "key2", "value2");
 325  *
 326  *   int local_port_id = message_port_register_local_port("HelloPort", message_port_receive_cb);
 327  *
 328  *   int ret = message_port_send_message_with_local_port("0123456789.BasicApp", "BasicAppPort", b, local_port_id);
 329  *
 330  *   bundle_free(b);
 331  * }
 332  * @endcode
 333  */
 334 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);
 335
 336 /**
 337  * @brief               Sends a trusted message with local port information to the message port of a remote application.
 338  * @details             This method is used for bidirectional communication. @n
 339  *                              It allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
 340  *
 341  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 342  *
 343  * @remarks             You muse release @a message using bundle_free() after sending the message.
 344  * @param[in]   remote_app_id           The ID of the remote application
 345  * @param[in]   remote_port                     The name of the remote message port
 346  * @param[in]   message                         The message to be passed to the remote application, the recommended message size is under 4KB
 347  * @param[in]   local_port_id           The message port ID returned by message_port_register_local_port() or message_port_register_trusted_local_port()
 348  * @return              0 on success,
 349  *                              otherwise a negative error value
 350  * @retval              #MESSAGE_PORT_ERROR_NONE                                        Successful
 351  * @retval              #MESSAGE_PORT_ERROR_INVALID_PARAMETER           The specified @a remote_app_id, @a remote_port or @a message is @c NULL and
 352                                                                                                         specified @a local_port_id is not positive
 353  * @retval              #MESSAGE_PORT_ERROR_OUT_OF_MEMORY                       Out of memory
 354  * @retval              #MESSAGE_PORT_ERROR_PORT_NOT_FOUND                      The port of the local or remote application cannot be found.
 355  * @retval              #MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH       The remote application is not signed with the same certificate.
 356  * @retval              #MESSAGE_PORT_ERROR_MAX_EXCEEDED                        The size of the message has exceeded the maximum limit.
 357  * @retval              #MESSAGE_PORT_ERROR_IO_ERROR                            Internal I/O error
 358  * @post                It invokes message_port_trusted_message_cb() on the remote application.
 359  * @see                 message_port_trusted_message_cb()
 360  * @see                 message_port_register_trusted_local_port()
 361  * @see                 message_port_unregister_trusted_local_port()
 362  */
 363 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);
 364
 365 /**
 366  * @}
 367  */
 368
 369 #ifdef __cplusplus
 370 }
 371 #endif
 372
 373 #endif /* __TIZEN_APPFW_MESSAGE_PORT_H__ */