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