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