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