1 /* vi: set et sw=4 ts=4 cino=t0,(0: */
2 /* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
4 * This file is part of message-port.
6 * Copyright (C) 2013 Intel Corporation.
8 * Contact: Amarnath Valluri <amarnath.valluri@linux.intel.com>
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.
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.
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
26 #ifndef __MESSAGE_PORT_H
27 #define __MESSAGE_PORT_H
31 # define EXPORT_API __attribute__((visibility("default")))
41 typedef gboolean bool;
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
56 * Enumerations of error code, that return by messeage port API.
59 typedef enum _messageport_error_e
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;
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.
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.
83 typedef void (*messageport_message_cb)(int id, const char* remote_app_id, const char* remote_port, bool trusted_message, bundle* message);
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
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.
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
100 messageport_register_local_port(const char* local_port, messageport_message_cb callback);
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
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.
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
117 messageport_register_trusted_local_port(const char* local_port, messageport_message_cb callback);
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.
125 * Checks if the message port #remote_port of a remote application #remote_app_id is registered.
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
133 EXPORT_API messageport_error_e
134 messageport_check_remote_port(const char* remote_app_id, const char *remote_port, bool *exist);
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
141 * Checks if the trusted message port #remote_port of a remote application #remote_app_id is registered.
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
149 EXPORT_API messageport_error_e
150 messageport_check_trusted_remote_port(const char* remote_app_id, const char *remote_port, bool *exist);
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
158 * Sends a message to the message port of a remote application.
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
168 * #include <message-port.h>
170 * bundle *b = bundle_create();
171 * bundle_add(b, "key1", "value1");
172 * bundle_add(b, "key2", "value2");
174 * int ret = messageport_send_message("0123456789.BasicApp", "BasicAppPort", b);
179 EXPORT_API messageport_error_e
180 messageport_send_message(const char* remote_app_id, const char* remote_port, bundle* message);
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
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.
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
199 EXPORT_API messageport_error_e
200 messageport_send_trusted_message(const char* remote_app_id, const char* remote_port, bundle* message);
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
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.
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
221 * #include <message-port.h>
224 * OnMessageReceived(int id, const char* remote_app_id, const char* remote_port, bool trusted_port, bundle* data)
228 * int main(int argc, char *argv[])
230 * bundle *b = bundle_create();
231 * bundle_add(b, "key1", "value1");
232 * bundle_add(b, "key2", "value2");
234 * int id = messageport_register_local_port("HelloPort", OnMessageReceived);
236 * int ret = messageport_send_bidirectional_message(id, "0123456789.BasicApp", "BasicAppPort", b);
241 EXPORT_API messageport_error_e
242 messageport_send_bidirectional_message(int id, const char* remote_app_id, const char* remote_port, bundle* message);
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
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.
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
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);
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
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().
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
278 EXPORT_API messageport_error_e
279 messageport_get_local_port_name(int id, char **name);
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
286 * Checks if the local message port is trusted.
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
293 EXPORT_API messageport_error_e
294 messageport_check_trusted_local_port(int id, bool *is_trusted);
298 #endif /* __MESSAGE_PORT_H */