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
|
//
// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// 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 __APPFW_MESSAGE_PORT_H__
#define __APPFW_MESSAGE_PORT_H__
#include <bundle.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Enumerations of error code for Application.
*/
typedef enum
{
MESSAGEPORT_ERROR_NONE = 0, /**< Successful */
MESSAGEPORT_ERROR_IO_ERROR = -1, /**< Internal I/O error */
MESSAGEPORT_ERROR_OUT_OF_MEMORY = -2, /**< Out of memory */
MESSAGEPORT_ERROR_INVALID_PARAMETER = -3, /**< Invalid parameter */
MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND = -4, /**< The message port of the remote application is not found */
MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH = -5, /**< The remote application is not signed with the same certificate */
MESSAGEPORT_ERROR_MAX_EXCEEDED = -6, /**< The size of message has exceeded the maximum limit */
} messageport_error_e;
/**
* @brief Called when a message is received from the remote application.
*
* @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
* @param [in] remote_app_id The ID of the remote application which has sent this message
* @param [in] remote_port The name of the remote message port
* @param [in] trusted_message @c true if the trusted remote message port is ready to receive the response data
* @param [in] data the data passed from the remote application
* @remarks @a data must be released with bundle_free() by you
* @remark @a remote_app_id and @a remote_port will be set if the remote application sends a bidirectional message, otherwise they are NULL.
*/
typedef void (*messageport_message_cb)(int id, const char* remote_app_id, const char* remote_port, bool trusted_message, bundle* data);
/**
* @brief Registers the local message port.
*
* @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
* @return A message port id on success, otherwise a negative error value.
* @retval #MESSAGEPORT_ERROR_NONE Successful
* @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
*/
int messageport_register_local_port(const char* local_port, messageport_message_cb callback);
/**
* @brief Registers the trusted local message port.
*
* @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
* @return A message port id on success, otherwise a negative error value.
* @retval #MESSAGEPORT_ERROR_NONE Successful
* @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
*/
int messageport_register_trusted_local_port(const char* local_port, messageport_message_cb callback);
/**
* @brief Unregisters the local message port.
*
* @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
* @return 0 on success, otherwise a negative error value.
* @retval #MESSAGEPORT_ERROR_NONE Successful
* @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
*/
int messageport_unregister_local_port(int id);
/**
* @brief Checks if the message port of a remote application is registered.
*
* @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 @c true if the message port of the remote application exists, otherwise @c false
* @return 0 on success, otherwise a negative error value.
* @retval #MESSAGEPORT_ERROR_NONE Successful
* @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
*/
int messageport_check_remote_port(const char* remote_app_id, const char *remote_port, bool* exist);
/**
* @brief Checks if the trusted message port of a remote application is registered.
*
* @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 @c true if the message port of the remote application exists, otherwise @c false
* @return 0 on success, otherwise a negative error value.
* @retval #MESSAGEPORT_ERROR_NONE Successful
* @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
* @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
*/
int messageport_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.
*
* @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 #MESSAGEPORT_ERROR_NONE Successful
* @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
* @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
* @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
*
* @code
* #include <message-port.h>
*
* bundle *b = bundle_create();
* bundle_add(b, "key1", "value1");
* bundle_add(b, "key2", "value2");
*
* int ret = messageport_send_message("0123456789.BasicApp", "BasicAppPort", b);
*
* bundle_free(b);
* @endcode
*/
int messageport_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.
*
* @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 #MESSAGEPORT_ERROR_NONE Successful
* @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
* @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
* @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
* @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
*/
int messageport_send_trusted_message(const char* remote_app_id, const char* remote_port, bundle* message);
/**
* @brief Sends a message to the message port of a remote application. This method is used for the bidirectional communication.
*
* @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
* @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 #MESSAGEPORT_ERROR_NONE Successful
* @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
* @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
* @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
*
* @code
* #include <message-port.h>
*
* static void
* OnMessageReceived(int id, const char* remote_app_id, const char* remote_port, bool trusted_port, bundle* data)
* {
* }
*
* int main(int argc, char *argv[])
* {
* bundle *b = bundle_create();
* bundle_add(b, "key1", "value1");
* bundle_add(b, "key2", "value2");
*
* int id = messageport_register_local_port("HelloPort", OnMessageReceived);
*
* int ret = messageport_send_message(id, "0123456789.BasicApp", "BasicAppPort", b);
*
* bundle_free(b);
* }
*/
int messageport_send_bidirectional_message(int id, const char* remote_app_id, const char* remote_port, bundle* data);
/**
* @brief Sends a trusted message to the message port of a remote application. This method is used for the bidirectional communication.
*
* @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
* @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 #MESSAGEPORT_ERROR_NONE Successful
* @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
* @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
* @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
* @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
* @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
*/
int messageport_send_bidirectional_trusted_message(int id, const char* remote_app_id, const char* remote_port, bundle* data);
/**
* @brief Gets the name of the local message port.
*
* @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
* @param [out] name The name of the local message port
* @return 0 on success, otherwise a negative error value.
* @retval #MESSAGEPORT_ERROR_NONE Successful
* @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
* @remarks @a name must be released with free() by you
*/
int messageport_get_local_port_name(int id, char **name);
/**
* @brief Checks if the local message port is trusted.
*
* @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
* @param [out] @c true if the local message port is trusted
* @return 0 on success, otherwise a negative error value.
* @retval #MESSAGEPORT_ERROR_NONE Successful
* @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
*/
int messageport_check_trusted_local_port(int id, bool *trusted);
/**
* @}
*/
#ifdef __cplusplus
}
#endif
#endif /* __APPFW_MESSAGE_PORT_H__ */
|
