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