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.
  59  *
  60  * @param [in] local_port the name of the local message port
  61  * @param [in] callback The callback function to be called when a message is received
  62  * @return A message port id on success, otherwise a negative error value.
  63  * @retval #MESSAGEPORT_ERROR_NONE Successful
  64  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
  65  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
  66  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
  67  */
  68 int messageport_register_local_port(const char* local_port, messageport_message_cb callback);
  69
  70 /**
  71  * @brief Registers the trusted local message port.
  72  *
  73  * @param [in] local_port the name of the local message port
  74  * @param [in] callback The callback function to be called when a message is received
  75  * @return A message port id on success, otherwise a negative error value.
  76  * @retval #MESSAGEPORT_ERROR_NONE Successful
  77  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
  78  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
  79  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
  80  */
  81 int messageport_register_trusted_local_port(const char* local_port, messageport_message_cb callback);
  82
  83
  84 /**
  85  * @brief Unregisters the local message port.
  86  *
  87  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
  88  * @return 0 on success, otherwise a negative error value.
  89  * @retval #MESSAGEPORT_ERROR_NONE Successful
  90  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
  91  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
  92  */
  93 int messageport_unregister_local_port(int id);
  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 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 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
 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 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.
 154  *
 155  * @param [in] remote_app_id The ID of the remote application
 156  * @param [in] remote_port the name of the remote message port
 157  * @param [in] message the message to be passed to the remote application
 158  * @return 0 on success, otherwise a negative error value.
 159  * @retval #MESSAGEPORT_ERROR_NONE Successful
 160  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 161  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 162  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 163  * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 164  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 165  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 166  */
 167 int messageport_send_trusted_message(const char* remote_app_id, const char* remote_port, bundle* message);
 168
 169 /**
 170  * @brief Sends a message to the message port of a remote application. This method is used for the bidirectional communication.
 171  *
 172  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 173  * @param [in] remote_app_id The ID of the remote application
 174  * @param [in] remote_port the name of the remote message port
 175  * @param [in] message the message to be passed to the remote application
 176  * @return 0 on success, otherwise a negative error value.
 177  * @retval #MESSAGEPORT_ERROR_NONE Successful
 178  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 179  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 180  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 181  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 182  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 183  *
 184  * @code
 185  * #include <message-port.h>
 186  *
 187  * static void
 188  * OnMessageReceived(int id, const char* remote_app_id, const char* remote_port, bool trusted_port, bundle* data)
 189  * {
 190  * }
 191  *
 192  * int main(int argc, char *argv[])
 193  * {
 194  *   bundle *b = bundle_create();
 195  *   bundle_add(b, "key1", "value1");
 196  *   bundle_add(b, "key2", "value2");
 197  *
 198  *   int id = messageport_register_local_port("HelloPort", OnMessageReceived);
 199  *
 200  *   int ret = messageport_send_message(id, "0123456789.BasicApp", "BasicAppPort", b);
 201  *
 202  *   bundle_free(b);
 203  * }
 204  */
 205 int messageport_send_bidirectional_message(int id, const char* remote_app_id, const char* remote_port, bundle* data);
 206
 207 /**
 208  * @brief Sends a trusted message to the message port of a remote application. This method is used for the bidirectional communication.
 209  *
 210  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 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 [in] message the message to be passed to the remote application
 214  * @return 0 on success, otherwise a negative error value.
 215  * @retval #MESSAGEPORT_ERROR_NONE Successful
 216  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 217  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 218  * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 219  * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 220  * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 221  * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 222  */
 223 int messageport_send_bidirectional_trusted_message(int id, const char* remote_app_id, const char* remote_port, bundle* data);
 224
 225
 226 /**
 227  * @brief Gets the name of the local message port.
 228  *
 229  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 230  * @param [out] name The name of the local message port
 231  * @return 0 on success, otherwise a negative error value.
 232  * @retval #MESSAGEPORT_ERROR_NONE Successful
 233  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 234  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 235  * @remarks @a name must be released with free() by you
 236  */
 237 int messageport_get_local_port_name(int id, char **name);
 238
 239 /**
 240  * @brief Checks if the local message port is trusted.
 241  *
 242  * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 243  * @param [out] @c true if the local message port is trusted
 244  * @return 0 on success, otherwise a negative error value.
 245  * @retval #MESSAGEPORT_ERROR_NONE Successful
 246  * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 247  * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 248  */
 249 int messageport_check_trusted_local_port(int id, bool *trusted);
 250
 251 /**
 252  * @}
 253  */
 254
 255 #ifdef __cplusplus
 256 }
 257 #endif
 258
 259 #endif /* __APPFW_MESSAGE_PORT_H__ */