1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
|
/*
* Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
*
* Licensed under the Apache License, Version 2.0 (the License);
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an AS IS BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef __TIZEN_APPFW_MESSAGE_PORT_H__
#define __TIZEN_APPFW_MESSAGE_PORT_H__
#ifdef __GNUC__
# ifndef EXPORT_API
# define EXPORT_API __attribute__((visibility("default")))
# endif
#else
# define EXPORT_API
#endif
#include <stdbool.h>
#include <bundle.h>
#include <tizen_error.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @addtogroup CAPI_MESSAGE_PORT_MODULE
* @{
*/
/**
* @brief Enumeration for error codes of a message port.
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*/
typedef enum
{
MESSAGE_PORT_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
MESSAGE_PORT_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< Internal I/O error */
MESSAGE_PORT_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
MESSAGE_PORT_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
MESSAGE_PORT_ERROR_PORT_NOT_FOUND = TIZEN_ERROR_MESSAGE_PORT | 0x01, /**< The message port of the remote application is not found */
MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH = TIZEN_ERROR_MESSAGE_PORT | 0x02, /**< The remote application is not signed with the same certificate */
MESSAGE_PORT_ERROR_MAX_EXCEEDED = TIZEN_ERROR_MESSAGE_PORT | 0x03, /**< The size of the message has exceeded the maximum limit */
MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLE = TIZEN_ERROR_MESSAGE_PORT | 0x04 /**< Resource is temporarily unavailable */
} message_port_error_e;
/**
* @brief Called when a message is received.
* @details The function is called when a message is received from the remote application.
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @remarks You can keep @a message using bundle_dup(). @n
* @a remote_port will be set only if the remote application sends a message with its port information using message_port_send_message_with_local_port(), otherwise it is @c NULL. @n
* When message is sent from remote application by message_port_send_message_with_local_port() in bidirectional communication, trusted_remote_port is used to check whether remote port is trusted port or not.
* This callback is called only in the main thread.
*
* @param[in] local_port_id The local message port ID returned by message_port_register_local_port()
* @param[in] remote_app_id The ID of the remote application that sent this message
* @param[in] remote_port The name of the remote message port
* @param[in] trusted_remote_port If @c true the remote port is a trusted port, otherwise if @c false it is not
* @param[in] message The message passed from the remote application
* @param[in] user_data The user data passed from the register function
* @pre Either message_port_send_message() or message_port_send_message_with_local_port() from the remote application will invoke this function if you register it using message_port_register_local_port().
* @see message_port_register_local_port()
* @see message_port_unregister_local_port()
* @see message_port_send_message()
* @see message_port_send_message_with_local_port()
*/
typedef void (*message_port_message_cb)(int local_port_id, const char *remote_app_id, const char *remote_port, bool trusted_remote_port, bundle *messagem, void *user_data);
/**
* @brief Called when a trusted message is received.
* @details This function is called when a trusted message is received from the remote application.
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @remarks You can keep @a message using bundle_dup(). @n
* @a remote_port will be set only if the remote application sends a message with its port information using message_port_send_trusted_message_with_local_port(), otherwise it is @c NULL. @n
* When message is sent from remote application by message_port_send_trusted_message_with_local_port() in bidirectional communication, trusted_remote_port is used to check whether remote port is trusted port or not.
* This callback is called only in the main thread.
* @param[in] trusted_local_port_id The message port ID returned by message_port_register_trusted_local_port()
* @param[in] remote_app_id The ID of the remote application that sent this message
* @param[in] remote_port The name of the remote message port
* @param[in] trusted_remote_port If @c true the remote port is a trusted port, otherwise if @c false it is not
* @param[in] message The message passed from the remote application
* @param[in] user_data The user data passed from the register function
* @pre Either message_port_send_trusted_message() or message_port_send_trusted_message_with_local_port() from the remote application will invoke this function if you register it using message_port_register_trusted_local_port().
* @see message_port_register_trusted_local_port()
* @see message_port_unregister_trusted_local_port()
* @see message_port_send_trusted_message()
* @see message_port_send_trusted_message_with_local_port()
*/
typedef void (*message_port_trusted_message_cb)(int trusted_local_port_id, const char *remote_app_id, const char *remote_port, bool trusted_remote_port, bundle *message, void *user_data);
/**
* @brief Registers the local message port.
* @details If the message port name is already registered, the previous local message port ID returns and the callback function is changed. \n
* Multiple message ports can be registered.
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @remarks The specified callback is called only in the main thread.
* @param[in] local_port The name of the local message port
* @param[in] callback The callback function to be called when a message is received
* @param[in] user_data The user data to be passed to the callback function
*
* @return A local message port ID on success,
* otherwise a negative error value
* @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a local_port or @a callback is NULL
* @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
* @see message_port_unregister_local_port()
*/
EXPORT_API int message_port_register_local_port(const char *local_port, message_port_message_cb callback, void *user_data);
/**
* @brief Registers the trusted local message port.
* @details If the message port name is already registered, the previous local message port ID returns and the callback function is changed. @n
* It allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer. @n
* Multiple message ports can be registered.
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @remarks The specified callback is called only in the main thread.
* @param[in] trusted_local_port The name of the trusted local message port
* @param[in] callback The callback function to be called when a trusted message is received
* @param[in] user_data The user data to be passed to the callback function
* @return A trusted local message port ID on success,
* otherwise a negative error value
* @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a trusted_local_port or @a callback is NULL
* @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
* @see message_port_unregister_trusted_local_port()
*/
EXPORT_API int message_port_register_trusted_local_port(const char *trusted_local_port, message_port_trusted_message_cb callback, void *user_data);
/**
* @brief Unregisters the local message port.
* @details This method unregisters the callback function with the specified local port ID.
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @param[in] local_port_id The local message port ID
* @return 0 on success,
* otherwise a negative error value
* @retval #MESSAGE_PORT_ERROR_NONE Successful
* @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a local_port_id is not positive
* @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The specified @a local_port_id cannot be found
* @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
* @see message_port_register_local_port()
*/
EXPORT_API int message_port_unregister_local_port(int local_port_id);
/**
* @brief Registers the trusted local message port.
* @details This method unregisters the callback function with the specified local port ID. @n
* It allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @param[in] trusted_local_port_id The trusted local message port ID
* @return @c 0 on success,
* otherwise a negative error value
* @retval #MESSAGE_PORT_ERROR_NONE Successful
* @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a trusted_local_port_id is not positive
* @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The specified @a trusted_local_port_id cannot be found
* @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
* @see message_port_register_trusted_local_port()
*/
EXPORT_API int message_port_unregister_trusted_local_port(int trusted_local_port_id);
/**
* @brief Checks whether the message port of a remote application is registered.
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @remarks If this function returns a negative error value, the out parameter @a exist will not be changed.
* @param[in] remote_app_id The ID of the remote application
* @param[in] remote_port The name of the remote message port
* @param[out] exist If @c true the message port of the remote application exists,
* otherwise @c false
* @return @c 0 on success,
* otherwise a negative error value
* @retval #MESSAGE_PORT_ERROR_NONE Successful
* @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id or @a remote_port is NULL
* @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
*/
EXPORT_API int message_port_check_remote_port(const char *remote_app_id, const char *remote_port, bool *exist);
/**
* @brief Checks whether the trusted message port of a remote application is registered.
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @remarks If this function returns a negative error value, the out parameter @a exist will not be changed.
* @param[in] remote_app_id The ID of the remote application
* @param[in] remote_port The name of the remote message port
* @param[out] exist If @c true the message port of the remote application exists,
* otherwise @c false
* @return @c 0 on success,
* otherwise a negative error value
* @retval #MESSAGE_PORT_ERROR_NONE Successful
* @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id or @a remote_port is @c NULL
* @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
* @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
*/
EXPORT_API int message_port_check_trusted_remote_port(const char *remote_app_id, const char *remote_port, bool *exist);
/**
* @brief Sends a message to the message port of a remote application.
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @remarks @a message must be released with bundle_free() after sending the message.
* @param[in] remote_app_id The ID of the remote application
* @param[in] remote_port The name of the remote message port
* @param[in] message The message to be passed to the remote application, the recommended message size is under 4KB
* @return 0 on success, otherwise a negative error value
* @retval #MESSAGE_PORT_ERROR_NONE Successful
* @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id, @a remote_port or @a message is NULL
* @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The message port of the remote application cannot be found
* @retval #MESSAGE_PORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
* @retval #MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLE Resource temporarily unavailable
* @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
* @post It invokes message_port_message_cb() on the remote application.
* @see message_port_message_cb()
* @see message_port_register_local_port()
* @see message_port_unregister_local_port()
*
* @code
* #include <message_port.h>
*
* bundle *b = bundle_create();
* bundle_add(b, "key1", "value1");
* bundle_add(b, "key2", "value2");
*
* int ret = message_port_send_message("0123456789.BasicApp", "BasicAppPort", b);
*
* bundle_free(b);
* @endcode
*/
EXPORT_API int message_port_send_message(const char *remote_app_id, const char *remote_port, bundle *message);
/**
* @brief Sends a trusted message to the message port of a remote application.
* @details This method allows communication only if the applications are signed with the same certificate which is uniquely assigned to the developer.
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @remarks You must release @a message using bundle_free() after sending the message.
* @param[in] remote_app_id The ID of the remote application
* @param[in] remote_port The name of the remote message port
* @param[in] message The message to be passed to the remote application, the recommended message size is under 4KB
* @return 0 on success,
* otherwise a negative error value
* @retval #MESSAGE_PORT_ERROR_NONE Successful
* @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id, @a remote_port or @a message is @c NULL
* @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The message port of the remote application cannot be found
* @retval #MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
* @retval #MESSAGE_PORT_ERROR_MAX_EXCEEDED The size of the message has exceeded the maximum limit
* @retval #MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLE Resource is temporarily unavailable
* @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
* @post It invokes message_port_trusted_message_cb() on the remote application.
* @see message_port_trusted_message_cb()
* @see message_port_register_trusted_local_port()
* @see message_port_unregister_trusted_local_port()
*/
EXPORT_API int message_port_send_trusted_message(const char *remote_app_id, const char *remote_port, bundle *message);
/**
* @brief Sends a message with local port information to the message port of a remote application.
* @details This method is used for bidirectional communication.
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @remarks You must releas @a message using bundle_free() after sending the message.
* @param[in] remote_app_id The ID of the remote application
* @param[in] remote_port The name of the remote message port
* @param[in] message The message to be passed to the remote application, the recommended message size is under 4KB
* @param[in] local_port_id The message port ID returned by message_port_register_local_port() or message_port_register_trusted_local_port()
* @return @c 0 on success,
* otherwise a negative error value
* @retval #MESSAGE_PORT_ERROR_NONE Successful
* @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id, @a remote_port or @a message is @c NULL and
The specified @a local_port_id is not positive
* @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The port of the local or remote application cannot be found
* @retval #MESSAGE_PORT_ERROR_MAX_EXCEEDED The size of the message has exceeded the maximum limit
* @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
* @post It invokes message_port_message_cb() on the remote application.
* @see message_port_message_cb()
* @see message_port_register_local_port()
* @see message_port_unregister_local_port()
*
* @code
* #include <message_port.h>
*
* static void
* message_port_receive_cb(int local_port_id, const char *remote_app_id, const char *remote_port, bundle *message)
* {
* }
*
* int main(int argc, char *argv[])
* {
* bundle *b = bundle_create();
* bundle_add(b, "key1", "value1");
* bundle_add(b, "key2", "value2");
*
* int local_port_id = message_port_register_local_port("HelloPort", message_port_receive_cb);
*
* int ret = message_port_send_message_with_local_port("0123456789.BasicApp", "BasicAppPort", b, local_port_id);
*
* bundle_free(b);
* }
* @endcode
*/
EXPORT_API int message_port_send_message_with_local_port(const char *remote_app_id, const char *remote_port, bundle *message, int local_port_id);
/**
* @brief Sends a trusted message with local port information to the message port of a remote application.
* @details This method is used for bidirectional communication. @n
* It allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
*
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @remarks You muse release @a message using bundle_free() after sending the message.
* @param[in] remote_app_id The ID of the remote application
* @param[in] remote_port The name of the remote message port
* @param[in] message The message to be passed to the remote application, the recommended message size is under 4KB
* @param[in] local_port_id The message port ID returned by message_port_register_local_port() or message_port_register_trusted_local_port()
* @return 0 on success,
* otherwise a negative error value
* @retval #MESSAGE_PORT_ERROR_NONE Successful
* @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id, @a remote_port or @a message is @c NULL and
specified @a local_port_id is not positive
* @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The port of the local or remote application cannot be found.
* @retval #MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate.
* @retval #MESSAGE_PORT_ERROR_MAX_EXCEEDED The size of the message has exceeded the maximum limit.
* @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
* @post It invokes message_port_trusted_message_cb() on the remote application.
* @see message_port_trusted_message_cb()
* @see message_port_register_trusted_local_port()
* @see message_port_unregister_trusted_local_port()
*/
EXPORT_API int message_port_send_trusted_message_with_local_port(const char *remote_app_id, const char *remote_port, bundle *message, int local_port_id);
/**
* @}
*/
#ifdef __cplusplus
}
#endif
#endif /* __TIZEN_APPFW_MESSAGE_PORT_H__ */
|
