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 #ifdef __GNUC__
  23 #       ifndef EXPORT_API
  24 #               define EXPORT_API __attribute__((visibility("default")))
  25 #       endif
  26 #else
  27 #       define EXPORT_API
  28 #endif
  29
  30 #include <bundle.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /**
  37  * @brief Enumerations of error code for Application.
  38  */
  39 typedef enum
  40 {
  41         MESSAGEPORT_ERROR_NONE = 0, /**< Successful */
  42         MESSAGEPORT_ERROR_IO_ERROR = -1,                /**< Internal I/O error */
  43         MESSAGEPORT_ERROR_OUT_OF_MEMORY = -2,           /**< Out of memory */
  44         MESSAGEPORT_ERROR_INVALID_PARAMETER = -3,       /**< Invalid parameter */
  45         MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND = -4,           /**< The message port of the remote application is not found */
  46         MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH = -5,   /**< The remote application is not signed with the same certificate */
  47         MESSAGEPORT_ERROR_MAX_EXCEEDED = -6,    /**< The size of message has exceeded the maximum limit */
  48         MESSAGEPORT_ERROR_RESOURCE_UNAVAILABLE = -7,    /**< Resource temporarily unavailable */
  49 } messageport_error_e;
  50
  51
  52 /**
  53  * @brief   Called when a message is received from the remote application.
  54  *
  55  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
  56  * @param [in] remote_app_id The ID of the remote application which has sent this message
  57  * @param [in] remote_port The name of the remote message port
  58  * @param [in] trusted_message @c true if the trusted remote message port is ready to receive the response data
  59  * @param [in] data the data passed from the remote application
  60  * @remarks @a data must be released with bundle_free() by you
  61  * @remark @a remote_app_id and @a remote_port will be set if the remote application sends a bidirectional message, otherwise they are NULL.
  62  */
  63 typedef void (*messageport_message_cb)(int id, const char* remote_app_id, const char* remote_port, bool trusted_message, bundle* data);
  64
  65
  66 /**
  67  * @brief Registers the local message port. @n
  68  * If the message port name is already registered, the previous message port id returns and the callback function is changed.
  69  *
  70  * @param [in] local_port the name of the local message port
  71  * @param [in] callback The callback function to be called when a message is received
  72  * @return A message port id on success, otherwise a negative error value.
  73  * @retval #MESSAGEPORT_ERROR_NONE Successful
  74  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
  75  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
  76  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
  77  */
  78 EXPORT_API int messageport_register_local_port(const char* local_port, messageport_message_cb callback);
  79
  80 /**
  81  * @brief Registers the trusted local message port. @n
  82  * If the message port name is already registered, the previous message port id returns and the callback function is changed. @n
  83  * This allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
  84  *
  85  * @param [in] local_port the name of the local message port
  86  * @param [in] callback The callback function to be called when a message is received
  87  * @return A message port id on success, otherwise a negative error value.
  88  * @retval #MESSAGEPORT_ERROR_NONE Successful
  89  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
  90  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
  91  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
  92  */
  93 EXPORT_API int messageport_register_trusted_local_port(const char* local_port, messageport_message_cb callback);
  94
  95 /**
  96  * @brief Checks if the message port of a remote application is registered.
  97  *
  98  * @param [in] remote_app_id The ID of the remote application
  99  * @param [in] remote_port the name of the remote message port
 100  * @param [out] exist @c true if the message port of the remote application exists, otherwise @c false
 101  * @return 0 on success, otherwise a negative error value.
 102  * @retval #MESSAGEPORT_ERROR_NONE Successful
 103  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 104  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 105  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 106  */
 107 EXPORT_API int messageport_check_remote_port(const char* remote_app_id, const char *remote_port, bool* exist);
 108
 109 /**
 110  * @brief Checks if the trusted message port of a remote application is registered.
 111  *
 112  * @param [in] remote_app_id The ID of the remote application
 113  * @param [in] remote_port the name of the remote message port
 114  * @param [out] exist @c true if the message port of the remote application exists, otherwise @c false
 115  * @return 0 on success, otherwise a negative error value.
 116  * @retval #MESSAGEPORT_ERROR_NONE Successful
 117  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 118  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 119  * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 120  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 121  */
 122 EXPORT_API int messageport_check_trusted_remote_port(const char* remote_app_id, const char *remote_port, bool* exist);
 123
 124 /**
 125  * @brief Sends a message to the message port of a remote application.
 126  *
 127  * @param [in] remote_app_id The ID of the remote application
 128  * @param [in] remote_port the name of the remote message port
 129  * @param [in] message the message to be passed to the remote application, the recommended message size is under 4KB
 130  * @return 0 on success, otherwise a negative error value.
 131  * @retval #MESSAGEPORT_ERROR_NONE Successful
 132  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 133  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 134  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 135  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 136  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 137  *
 138  * @code
 139  * #include <message-port.h>
 140  *
 141  * bundle *b = bundle_create();
 142  * bundle_add(b, "key1", "value1");
 143  * bundle_add(b, "key2", "value2");
 144  *
 145  * int ret = messageport_send_message("0123456789.BasicApp", "BasicAppPort", b);
 146  *
 147  * bundle_free(b);
 148  * @endcode
 149  */
 150 EXPORT_API int messageport_send_message(const char* remote_app_id, const char* remote_port, bundle* message);
 151
 152 /**
 153  * @brief Sends a trusted message to the message port of a remote application. @n
 154  *  This allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
 155  *
 156  * @param [in] remote_app_id The ID of the remote application
 157  * @param [in] remote_port the name of the remote message port
 158  * @param [in] message the message to be passed to the remote application, the recommended message size is under 4KB
 159  * @return 0 on success, otherwise a negative error value.
 160  * @retval #MESSAGEPORT_ERROR_NONE Successful
 161  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 162  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 163  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 164  * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 165  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 166  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 167  */
 168 EXPORT_API int messageport_send_trusted_message(const char* remote_app_id, const char* remote_port, bundle* message);
 169
 170 /**
 171  * @brief Sends a message to the message port of a remote application. This method is used for the bidirectional communication.
 172  *
 173  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 174  * @param [in] remote_app_id The ID of the remote application
 175  * @param [in] remote_port the name of the remote message port
 176  * @param [in] message the message to be passed to the remote application, the recommended message size is under 4KB
 177  * @return 0 on success, otherwise a negative error value.
 178  * @retval #MESSAGEPORT_ERROR_NONE Successful
 179  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 180  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 181  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 182  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 183  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 184  *
 185  * @code
 186  * #include <message-port.h>
 187  *
 188  * static void
 189  * OnMessageReceived(int id, const char* remote_app_id, const char* remote_port, bool trusted_port, bundle* data)
 190  * {
 191  * }
 192  *
 193  * int main(int argc, char *argv[])
 194  * {
 195  *   bundle *b = bundle_create();
 196  *   bundle_add(b, "key1", "value1");
 197  *   bundle_add(b, "key2", "value2");
 198  *
 199  *   int id = messageport_register_local_port("HelloPort", OnMessageReceived);
 200  *
 201  *   int ret = messageport_send_bidirectional_message(id, "0123456789.BasicApp", "BasicAppPort", b);
 202  *
 203  *   bundle_free(b);
 204  * }
 205  */
 206 EXPORT_API int messageport_send_bidirectional_message(int id, const char* remote_app_id, const char* remote_port, bundle* data);
 207
 208 /**
 209  * @brief Sends a trusted message to the message port of a remote application. This method is used for the bidirectional communication.
 210  *  This allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
 211  *
 212  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 213  * @param [in] remote_app_id The ID of the remote application
 214  * @param [in] remote_port the name of the remote message port
 215  * @param [in] message the message to be passed to the remote application, the recommended message size is under 4KB
 216  * @return 0 on success, otherwise a negative error value.
 217  * @retval #MESSAGEPORT_ERROR_NONE Successful
 218  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 219  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 220  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 221  * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 222  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 223  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 224  */
 225 EXPORT_API int messageport_send_bidirectional_trusted_message(int id, const char* remote_app_id, const char* remote_port, bundle* data);
 226
 227
 228 /**
 229  * @brief Gets the name of the local message port.
 230  *
 231  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 232  * @param [out] name The name of the local message port
 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  * @remarks @a name must be released with free() by you
 238  */
 239 EXPORT_API int messageport_get_local_port_name(int id, char **name);
 240
 241 /**
 242  * @brief Checks if the local message port is trusted.
 243  *
 244  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 245  * @param [out] @c true if the local message port is trusted
 246  * @return 0 on success, otherwise a negative error value.
 247  * @retval #MESSAGEPORT_ERROR_NONE Successful
 248  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 249  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 250  */
 251 EXPORT_API int messageport_check_trusted_local_port(int id, bool *trusted);
 252
 253 /**
 254  * @}
 255  */
 256
 257 #ifdef __cplusplus
 258 }
 259 #endif
 260
 261 #endif /* __APPFW_MESSAGE_PORT_H__ */