lib/message-port.h

   1 /* vi: set et sw=4 ts=4 cino=t0,(0: */
   2 /* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   3 /*
   4  * This file is part of message-port.
   5  *
   6  * Copyright (C) 2013 Intel Corporation.
   7  *
   8  * Contact: Amarnath Valluri <amarnath.valluri@linux.intel.com>
   9  *
  10  * This library is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public
  12  * License as published by the Free Software Foundation; either
  13  * version 2.1 of the License, or (at your option) any later version.
  14  *
  15  * This library is distributed in the hope that it will be useful, but
  16  * WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with this library; if not, write to the Free Software
  22  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  23  * 02110-1301 USA
  24  */
  25
  26 #ifndef __MESSAGE_PORT_H
  27 #define __MESSAGE_PORT_H
  28
  29 #ifdef __GNUC__
  30 #   ifndef EXPORT_API
  31 #       define EXPORT_API __attribute__((visibility("default")))
  32 #   endif
  33 #else
  34 #   define EXPORT_API
  35 #endif
  36
  37 #include <bundle.h>
  38 #include <glib.h>
  39
  40 #ifndef __cplusplus
  41 typedef guint8 bool;
  42 #endif
  43
  44 G_BEGIN_DECLS
  45
  46 /**
  47  * messageport_error_e
  48  * @MESSAGEPORT_ERROR_NONE: No error, operation was successful
  49  * @MESSAGEPORT_ERROR_IO_ERROR: Internal I/O error
  50  * @MESSAGEPORT_ERROR_OUT_OF_MEMORY: Out of memory
  51  * @MESSAGEPORT_ERROR_INVALID_PARAMETER: Invalid paramenter passed
  52  * @MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND: The message port of the remote application is not found
  53  * @MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH: The remote application is not signed with the same certificate
  54  * @MESSAGEPORT_ERROR_MAX_EXCEEDED: The size of message has exceeded the maximum limit
  55  *
  56  * Enumerations of error code, that return by messeage port API.
  57  *
  58  */
  59 typedef enum _messageport_error_e
  60 {
  61     MESSAGEPORT_ERROR_NONE = 0,
  62     MESSAGEPORT_ERROR_IO_ERROR = -1,
  63     MESSAGEPORT_ERROR_OUT_OF_MEMORY = -2,
  64     MESSAGEPORT_ERROR_INVALID_PARAMETER = -3,
  65     MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND = -4,
  66     MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH = -5,
  67     MESSAGEPORT_ERROR_MAX_EXCEEDED = -6,
  68 } messageport_error_e;
  69
  70 /**
  71  * messageport_message_cb:
  72  * @id: The ID of the local message port to which the message was sent.
  73  * @remote_app_id: The ID of the remote application which has sent this message, or NULL
  74  * @remote_port: The name of the remote message port, or NULL
  75  * @trusted_message: TRUE if the remote message port is trusted port, i.e, it receives message from trusted applications.
  76  * @message: The message received.
  77  *
  78  * This is the function type of the callback used for #messageport_register_local_port or #messageport_register_trusted_local_port.
  79  * This is called when a message is received from the remote application, #remote_app_id and #remtoe_port will be set
  80  * if the remote application sends a bidirectional message, otherwise they are NULL.
  81  *
  82  */
  83 typedef void (*messageport_message_cb)(int id, const char* remote_app_id, const char* remote_port, bool trusted_message, bundle* message);
  84
  85 /**
  86  * messageport_register_local_port:
  87  * @local_port: local_port the name of the local message port
  88  * @callback: callback The callback function to be called when a message is received at this port
  89  *
  90  * Registers the local message port with name #local_port. If the message port name is already registered,
  91  * the previous message port id returned, and the callback function is updated with #callback.
  92  * The #callback function is called when a message is received from a remote application.
  93  *
  94  * Returns: A message port id on success, otherwise a negative error value.
  95  *          #MESSAGEPORT_ERROR_INVALID_PARAMETER If either #local_port or #callback is missing or invalid.
  96  *          #MESSAGEPORT_ERROR_OUT_OF_MEMORY Memory error occured
  97  *          #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
  98  */
  99 EXPORT_API int
 100 messageport_register_local_port(const char* local_port, messageport_message_cb callback);
 101
 102 /**
 103  * messageport_register_trusted_local_port:
 104  * @local_port:  local_port the name of the local message port
 105  * @callback: callback The callback function to be called when a message is received
 106  *
 107  * Registers the trusted local message port with name #local_port. If the message port name is already registered,
 108  * the previous message port id returned, and the callback function is updated with #callback.
 109  * This allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
 110  *
 111  * Returns: A message port id on success, otherwise a negative error value.
 112  *          #MESSAGEPORT_ERROR_INVALID_PARAMETER If either #local_port or #callback is missing or invalid.
 113  *          #MESSAGEPORT_ERROR_OUT_OF_MEMORY Memory error occured
 114  *          #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 115  */
 116 EXPORT_API int
 117 messageport_register_trusted_local_port(const char* local_port, messageport_message_cb callback);
 118
 119 /**
 120  * messageport_check_remote_port:
 121  * @remote_app_id: The ID of the remote application
 122  * @remote_port: the name of the remote message port to check for.
 123  * @exist: Return location for status, or NULL.
 124  *
 125  * Checks if the message port #remote_port of a remote application #remote_app_id is registered.
 126  *
 127  * @param [out] exist @c true if the message port of the remote application exists, otherwise @c false
 128  * Returns: #MESSAGEPORT_ERROR_NONE if success, otherwise oa negative error value:
 129  *          #MESSAGEPORT_ERROR_INVALID_PARAMETER Either #remote_app_id or #remote_port is missing or invalid
 130  *          #MESSAGEPORT_ERROR_OUT_OF_MEMORY Memory error occured
 131  *          #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 132  */
 133 EXPORT_API messageport_error_e
 134 messageport_check_remote_port(const char* remote_app_id, const char *remote_port, bool *exist);
 135
 136 /**
 137  * messageport_check_trusted_remote_port:
 138  * @remote_app_id: The ID of the remote application
 139  * @remote_port: The name of the remote message port
 140  *
 141  * Checks if the trusted message port #remote_port of a remote application #remote_app_id is registered.
 142  *
 143  * Returns: #MESSAGEPORT_ERROR_NONE on success, otherwise a negative error value.
 144  *          #MESSAGEPORT_ERROR_INVALID_PARAMETER Either #remote_app_id or #remote_port is missing or invalid
 145  *          #MESSAGEPORT_ERROR_OUT_OF_MEMORY Memory error occured
 146  *          #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 147  *          #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 148  */
 149 EXPORT_API messageport_error_e
 150 messageport_check_trusted_remote_port(const char* remote_app_id, const char *remote_port, bool *exist);
 151
 152 /**
 153  * messageport_send_message:
 154  * @remote_app_id: The ID of the remote application
 155  * @remote_port: The name of the remote message port
 156  * @message: Message to be passed to the remote application, the recommended message size is under 4KB
 157  *
 158  * Sends a message to the message port of a remote application.
 159  *
 160  * Returns #MESSAGEPORT_ERROR_NONE on success, otherwise a negative error value.
 161  *         #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter passed
 162  *         #MESSAGEPORT_ERROR_OUT_OF_MEMORY Memory error occured
 163  *         #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 164  *         #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 165  *         #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 166  *
 167  * @code
 168  * #include <message-port.h>
 169  *
 170  * bundle *b = bundle_create();
 171  * bundle_add(b, "key1", "value1");
 172  * bundle_add(b, "key2", "value2");
 173  *
 174  * int ret = messageport_send_message("0123456789.BasicApp", "BasicAppPort", b);
 175  *
 176  * bundle_free(b);
 177  * @endcode
 178  */
 179 EXPORT_API messageport_error_e
 180 messageport_send_message(const char* remote_app_id, const char* remote_port, bundle* message);
 181
 182 /**
 183  * messageport_send_trusted_message:
 184  * @remote_app_id: The ID of the remote application
 185  * @remote_port: The name of the remote message port
 186  * @message: Message to be passed to the remote application, the recommended message size is under 4KB
 187  *
 188  * Sends a trusted message to the message port of a remote application. This allows communications only
 189  * if the applications are signed with the same certificate which is uniquely assigned to the developer.
 190  *
 191  * Returns #MESSAGEPORT_ERROR_NONE on success, otherwise a negative error value.
 192  *         #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter passed
 193  *         #MESSAGEPORT_ERROR_OUT_OF_MEMORY Memeory error occured
 194  *         #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 195  *         #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 196  *         #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 197  *         #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 198  */
 199 EXPORT_API messageport_error_e
 200 messageport_send_trusted_message(const char* remote_app_id, const char* remote_port, bundle* message);
 201
 202 /**
 203  * messageport_send_bidirectional_message:
 204  * @id: The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 205  * @remote_app_id: The ID of the remote application
 206  * @remote_port: The name of the remote message port
 207  * @message: Message to be passed to the remote application, the recommended message size is under 4KB
 208
 209  * Sends a message to the message port #remote_port of a remote application #remote_app_id.
 210  * This method is used for the bidirectional communication.
 211  * Remote application can send back the return message to the local message port referred by #id.
 212  *
 213  * Returns: #MESSAGEPORT_ERROR_NONE on success, otherwise a negative error value.
 214  *          #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter passed
 215  *          #MESSAGEPORT_ERROR_OUT_OF_MEMORY Memeory error occured
 216  *          #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 217  *          #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 218  *          #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 219  *
 220  * @code
 221  * #include <message-port.h>
 222  *
 223  * static void
 224  * OnMessageReceived(int id, const char* remote_app_id, const char* remote_port, bool trusted_port, bundle* data)
 225  * {
 226  * }
 227  *
 228  * int main(int argc, char *argv[])
 229  * {
 230  *   bundle *b = bundle_create();
 231  *   bundle_add(b, "key1", "value1");
 232  *   bundle_add(b, "key2", "value2");
 233  *
 234  *   int id = messageport_register_local_port("HelloPort", OnMessageReceived);
 235  *
 236  *   int ret = messageport_send_bidirectional_message(id, "0123456789.BasicApp", "BasicAppPort", b);
 237  *
 238  *   bundle_free(b);
 239  * }
 240  */
 241 EXPORT_API messageport_error_e
 242 messageport_send_bidirectional_message(int id, const char* remote_app_id, const char* remote_port, bundle* message);
 243
 244 /**
 245  * messageport_send_bidirectional_trusted_message:
 246  * @id: The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 247  * @remtoe_app_id: The ID of the remote application
 248  * @remtoe_port: The  name of the remote message port
 249  * @message: Message to be passed to the remote application, the recommended message size is under 4KB
 250  *
 251  * Sends a trusted message to the message port of a remote application. This method is used for the bidirectional communication.
 252  * Remote application can send back the return message to the local message port referred by #id.
 253  * This allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
 254  *
 255  * Returns: #MESSAGEPORT_ERROR_NONE on success, otherwise a negative error value.
 256  *          #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter passed
 257  *          #MESSAGEPORT_ERROR_OUT_OF_MEMORY Memeory error occured
 258  *          #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
 259  *          #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
 260  *          #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
 261  *          #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
 262  */
 263 EXPORT_API messageport_error_e
 264 messageport_send_bidirectional_trusted_message(int id, const char* remote_app_id, const char* remote_port, bundle* message);
 265
 266 /**
 267  * messageport_get_local_port_name:
 268  * @id: The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 269  * @name: Return location to hold name of the message port or NULL
 270  *
 271  * Gets the name of the local message port. On success, the #name is filled with the registered message port name, which muste be released with #free().
 272  *
 273  * Returns: #MESSAGEPORT_ERROR_NONE on success, otherwise a negative error value.
 274  *          #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
 275  *          #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND No local message port found for #id
 276  *          #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
 277  */
 278 EXPORT_API messageport_error_e
 279 messageport_get_local_port_name(int id, char **name);
 280
 281 /**
 282  * messageport_check_trusted_local_port:
 283  * @id: The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
 284  * @is_trusted: Return location to hold the trusted state of the local messge port
 285  *
 286  * Checks if the local message port is trusted.
 287  *
 288  * Returns: #MESSAGEPORT_ERROR_NONE on success, otherwise a negative error value.
 289  *          #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter passed
 290  *          #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND No local message port found for #id
 291  *          #MESSAGEPORT_ERROR_OUT_OF_MEMORY Memory error occured
 292  */
 293 EXPORT_API messageport_error_e
 294 messageport_check_trusted_local_port(int id, bool *is_trusted);
 295
 296 G_END_DECLS
 297
 298 #endif /* __MESSAGE_PORT_H */