lib/message-port.h

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