2 * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the License);
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an AS IS BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef __TIZEN_APPFW_MESSAGE_PORT_H__
18 #define __TIZEN_APPFW_MESSAGE_PORT_H__
22 #define EXPORT_API __attribute__((visibility("default")))
30 #include <tizen_error.h>
37 * @addtogroup CAPI_MESSAGE_PORT_MODULE
43 * @brief Enumeration for error codes of a message port.
44 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
47 MESSAGE_PORT_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
48 MESSAGE_PORT_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< Internal I/O error */
49 MESSAGE_PORT_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
50 MESSAGE_PORT_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
51 MESSAGE_PORT_ERROR_PORT_NOT_FOUND = TIZEN_ERROR_MESSAGE_PORT | 0x01, /**< The message port of the remote application is not found */
52 MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH = TIZEN_ERROR_MESSAGE_PORT | 0x02, /**< The remote application is not signed with the same certificate */
53 MESSAGE_PORT_ERROR_MAX_EXCEEDED = TIZEN_ERROR_MESSAGE_PORT | 0x03, /**< The size of the message has exceeded the maximum limit */
54 MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLE = TIZEN_ERROR_MESSAGE_PORT | 0x04 /**< Resource is temporarily unavailable */
55 } message_port_error_e;
59 * @brief Called when a message is received.
60 * @details The function is called when a message is received from the remote application.
61 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
62 * @remarks @a message is automatically freed by framework when callback returned, you can keep @a message using bundle_dup() @n
63 * @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
64 * 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
65 * This callback is called only in the main thread.
66 * @param[in] local_port_id The local message port ID returned by message_port_register_local_port()
67 * @param[in] remote_app_id The ID of the remote application that sent this message
68 * @param[in] remote_port The name of the remote message port
69 * @param[in] trusted_remote_port If @c true, the remote port is a trusted port; otherwise if @c false, it is not
70 * @param[in] message The message passed from the remote application
71 * @param[in] user_data The user data passed from the register function
72 * @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()
73 * @see message_port_register_local_port()
74 * @see message_port_unregister_local_port()
75 * @see message_port_send_message()
76 * @see message_port_send_message_with_local_port()
78 typedef void (*message_port_message_cb)(int local_port_id, const char *remote_app_id, const char *remote_port, bool trusted_remote_port, bundle *message, void *user_data);
82 * @brief Called when a trusted message is received.
83 * @details This function is called when a trusted message is received from the remote application.
84 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
85 * @remarks You can keep @a message using bundle_dup(). @n
86 * @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
87 * 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.
88 * This callback is called only in the main thread.
89 * @param[in] trusted_local_port_id The message port ID returned by message_port_register_trusted_local_port()
90 * @param[in] remote_app_id The ID of the remote application that sent this message
91 * @param[in] remote_port The name of the remote message port
92 * @param[in] trusted_remote_port If @c true, the remote port is a trusted port; otherwise if @c false, it is not
93 * @param[in] message The message passed from the remote application
94 * @param[in] user_data The user data passed from the register function
95 * @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().
96 * @see message_port_register_trusted_local_port()
97 * @see message_port_unregister_trusted_local_port()
98 * @see message_port_send_trusted_message()
99 * @see message_port_send_trusted_message_with_local_port()
101 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);
105 * @brief Called when a remote port is registered or unregistered.
106 * @details The function is called when a remote port is registered or unregistered
107 * from the remote application.
109 * @remarks @a remote_app_id and @a remote_port can be used until
110 * message_port_remove_registration_event_cb() is called for the watcher which reported
112 * @param[in] remote_app_id The ID of the remote application that sent this message
113 * @param[in] remote_port The name of the remote message port
114 * @param[in] trusted_remote_port Indicates whether remote port is trusted
115 * @param[in] user_data The user data passed from the register function
116 * @pre Called when a remote port is registered or unregistered if you add it using
117 * message_port_add_registered_cb() or message_port_add_unregistered_cb() respectively.
118 * @see message_port_add_registered_cb()
119 * @see message_port_add_unregistered_cb()
120 * @see message_port_remove_registration_event_cb()
122 typedef void (*message_port_registration_event_cb)(const char *remote_app_id,
123 const char *remote_port,
124 bool trusted_remote_port,
129 * @brief Registers the local message port.
130 * @details If the message port name is already registered, the previous local message port ID returns and the callback function is changed. \n
131 * Multiple message ports can be registered.
132 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
133 * @remarks The specified callback is called only in the main thread.
134 * @param[in] local_port The name of the local message port
135 * @param[in] callback The callback function to be called when a message is received
136 * @param[in] user_data The user data to be passed to the callback function
137 * @return A local message port ID on success,
138 * otherwise a negative error value
139 * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a local_port or @a callback is NULL
140 * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
141 * @retval MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
142 * @see message_port_unregister_local_port()
144 EXPORT_API int message_port_register_local_port(const char *local_port, message_port_message_cb callback, void *user_data);
148 * @brief Registers the trusted local message port.
149 * @details If the message port name is already registered, the previous local message port ID returns and the callback function is changed. @n
150 * It allows communications only if the applications are signed with the same certificate, which is uniquely assigned to the developer. @n
151 * Multiple message ports can be registered.
152 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
153 * @remarks The specified callback is called only in the main thread.
154 * @param[in] trusted_local_port The name of the trusted local message port
155 * @param[in] callback The callback function to be called when a trusted message is received
156 * @param[in] user_data The user data to be passed to the callback function
157 * @return A trusted local message port ID on success,
158 * otherwise a negative error value
159 * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a trusted_local_port or @a callback is NULL
160 * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
161 * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
162 * @see message_port_unregister_trusted_local_port()
164 EXPORT_API int message_port_register_trusted_local_port(const char *trusted_local_port, message_port_trusted_message_cb callback, void *user_data);
168 * @brief Unregisters the local message port.
169 * @details This method unregisters the callback function with the specified local port ID.
170 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
171 * @param[in] local_port_id The local message port ID
172 * @return @c 0 on success,
173 * otherwise a negative error value
174 * @retval #MESSAGE_PORT_ERROR_NONE Successful
175 * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a local_port_id is not positive
176 * @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The specified @a local_port_id cannot be found
177 * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
178 * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
179 * @see message_port_register_local_port()
181 EXPORT_API int message_port_unregister_local_port(int local_port_id);
185 * @brief Registers the trusted local message port.
186 * @details This method unregisters the callback function with the specified local port ID. @n
187 * It allows communications only if the applications are signed with the same certificate, which is uniquely assigned to the developer.
188 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
189 * @param[in] trusted_local_port_id The trusted local message port ID
190 * @return @c 0 on success,
191 * otherwise a negative error value
192 * @retval #MESSAGE_PORT_ERROR_NONE Successful
193 * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a trusted_local_port_id is not positive
194 * @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The specified @a trusted_local_port_id cannot be found
195 * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
196 * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
197 * @see message_port_register_trusted_local_port()
199 EXPORT_API int message_port_unregister_trusted_local_port(int trusted_local_port_id);
203 * @brief Checks whether the message port of a remote application is registered.
204 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
205 * @remarks If this function returns a negative error value, the out parameter @a exist will not be changed.
206 * @param[in] remote_app_id The ID of the remote application
207 * @param[in] remote_port The name of the remote message port
208 * @param[out] exist If @c true, the message port of the remote application exists;
210 * @return @c 0 on success,
211 * otherwise a negative error value
212 * @retval #MESSAGE_PORT_ERROR_NONE Successful
213 * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id or @a remote_port is NULL
214 * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
215 * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
217 EXPORT_API int message_port_check_remote_port(const char *remote_app_id, const char *remote_port, bool *exist);
221 * @brief Checks whether the trusted message port of a remote application is registered.
222 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
223 * @remarks If this function returns a negative error value, the out parameter @a exist will not be changed.
224 * @param[in] remote_app_id The ID of the remote application
225 * @param[in] remote_port The name of the remote message port
226 * @param[out] exist If @c true, the message port of the remote application exists;
228 * @return @c 0 on success,
229 * otherwise a negative error value
230 * @retval #MESSAGE_PORT_ERROR_NONE Successful
231 * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id or @a remote_port is @c NULL
232 * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
233 * @retval #MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
234 * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
236 EXPORT_API int message_port_check_trusted_remote_port(const char *remote_app_id, const char *remote_port, bool *exist);
240 * @brief Sends a message to the message port of a remote application.
241 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
242 * @remarks @a message must be released with bundle_free() after sending the message.
243 * @param[in] remote_app_id The ID of the remote application
244 * @param[in] remote_port The name of the remote message port
245 * @param[in] message The message to be passed to the remote application, the recommended message size is under 4KB
246 * @return @c 0 on success,
247 * otherwise a negative error value
248 * @retval #MESSAGE_PORT_ERROR_NONE Successful
249 * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id, @a remote_port or @a message is NULL
250 * @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The message port of the remote application cannot be found
251 * @retval #MESSAGE_PORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
252 * @retval #MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLE Resource temporarily unavailable
253 * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
254 * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
255 * @post It invokes message_port_message_cb() on the remote application.
256 * @see message_port_message_cb()
257 * @see message_port_register_local_port()
258 * @see message_port_unregister_local_port()
261 * #include <message_port.h>
262 * bundle *b = bundle_create();
263 * bundle_add(b, "key1", "value1");
264 * bundle_add(b, "key2", "value2");
265 * int ret = message_port_send_message("0123456789.BasicApp", "BasicAppPort", b);
269 EXPORT_API int message_port_send_message(const char *remote_app_id, const char *remote_port, bundle *message);
273 * @brief Sends a trusted message to the message port of a remote application.
274 * @details This method allows communication only if the applications are signed with the same certificate, which is uniquely assigned to the developer.
275 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
276 * @remarks You must release @a message using bundle_free() after sending the message.
277 * @param[in] remote_app_id The ID of the remote application
278 * @param[in] remote_port The name of the remote message port
279 * @param[in] message The message to be passed to the remote application, the recommended message size is under 4KB
280 * @return @c 0 on success,
281 * otherwise a negative error value
282 * @retval #MESSAGE_PORT_ERROR_NONE Successful
283 * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id, @a remote_port or @a message is @c NULL
284 * @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The message port of the remote application cannot be found
285 * @retval #MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
286 * @retval #MESSAGE_PORT_ERROR_MAX_EXCEEDED The size of the message has exceeded the maximum limit
287 * @retval #MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLE Resource is temporarily unavailable
288 * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
289 * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
290 * @post It invokes message_port_trusted_message_cb() on the remote application.
291 * @see message_port_trusted_message_cb()
292 * @see message_port_register_trusted_local_port()
293 * @see message_port_unregister_trusted_local_port()
295 EXPORT_API int message_port_send_trusted_message(const char *remote_app_id, const char *remote_port, bundle *message);
299 * @brief Sends a message with local port information to the message port of a remote application.
300 * @details This method is used for bidirectional communication.
301 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
302 * @remarks You must release @a message using bundle_free() after sending the message.
303 * @param[in] remote_app_id The ID of the remote application
304 * @param[in] remote_port The name of the remote message port
305 * @param[in] message The message to be passed to the remote application, the recommended message size is under 4KB
306 * @param[in] local_port_id The message port ID returned by message_port_register_local_port() or message_port_register_trusted_local_port()
307 * @return @c 0 on success,
308 * otherwise a negative error value
309 * @retval #MESSAGE_PORT_ERROR_NONE Successful
310 * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id, @a remote_port or @a message is @c NULL and
311 * The specified @a local_port_id is not positive
312 * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
313 * @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The port of the local or remote application cannot be found
314 * @retval #MESSAGE_PORT_ERROR_MAX_EXCEEDED The size of the message has exceeded the maximum limit
315 * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
316 * @post It invokes message_port_message_cb() on the remote application.
317 * @see message_port_message_cb()
318 * @see message_port_register_local_port()
319 * @see message_port_unregister_local_port()
322 * #include <message_port.h>
324 * static void message_port_receive_cb(int local_port_id, const char *remote_app_id, const char *remote_port, bundle *message) {}
327 * main(int argc, char *argv[])
329 * bundle *b = bundle_create();
330 * bundle_add(b, "key1", "value1");
331 * bundle_add(b, "key2", "value2");
333 * int local_port_id = message_port_register_local_port("HelloPort", message_port_receive_cb);
335 * int ret = message_port_send_message_with_local_port("0123456789.BasicApp", "BasicAppPort", b, local_port_id);
341 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);
345 * @brief Sends a trusted message with local port information to the message port of a remote application.
346 * @details This method is used for bidirectional communication. @n
347 * It allows communications only if the applications are signed with the same certificate, which is uniquely assigned to the developer.
348 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
349 * @remarks You muse release @a message using bundle_free() after sending the message.
350 * @param[in] remote_app_id The ID of the remote application
351 * @param[in] remote_port The name of the remote message port
352 * @param[in] message The message to be passed to the remote application, the recommended message size is under 4KB
353 * @param[in] local_port_id The message port ID returned by message_port_register_local_port() or message_port_register_trusted_local_port()
354 * @return @c 0 on success,
355 * otherwise a negative error value
356 * @retval #MESSAGE_PORT_ERROR_NONE Successful
357 * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id, @a remote_port or @a message is @c NULL and
358 * specified @a local_port_id is not positive
359 * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
360 * @retval #MESSAGE_PORT_ERROR_PORT_NOT_FOUND The port of the local or remote application cannot be found
361 * @retval #MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
362 * @retval #MESSAGE_PORT_ERROR_MAX_EXCEEDED The size of the message has exceeded the maximum limit
363 * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
364 * @post It invokes message_port_trusted_message_cb() on the remote application.
365 * @see message_port_trusted_message_cb()
366 * @see message_port_register_trusted_local_port()
367 * @see message_port_unregister_trusted_local_port()
369 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);
373 * @brief Adds a callback called when a remote port is registered.
374 * @details When remote port is registered, @a registered_cb function is called.
375 * Each added callback has its own separate watcher.
377 * @remarks The specified callback is called only in the main thread.
378 * @param[in] remote_app_id The ID of the remote application
379 * @param[in] remote_port The name of the remote message port
380 * @param[in] trusted_remote_port Indicates whether remote port is trusted
381 * @param[in] registered_cb The callback function to be called
382 * when remote port is registered
383 * @param[in] user_data The user data to be passed to the callback function
384 * @param[out] watcher_id The ID of the watcher which is monitoring the remote port
385 * registration events
386 * @return @c 0 on success,
387 * otherwise a negative error value
388 * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id or @a remote_port
389 * or @a registered_cb is NULL
390 * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
391 * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
392 * @see message_port_registration_event_cb()
393 * @see message_port_add_unregistered_cb()
394 * @see message_port_remove_registration_event_cb()
396 EXPORT_API int message_port_add_registered_cb(const char *remote_app_id,
397 const char *remote_port,
398 bool trusted_remote_port,
399 message_port_registration_event_cb registered_cb,
404 * @brief Adds a callback called when a remote port is unregistered.
405 * @details When the remote port is unregistered, @a unregistered_cb function is called.
406 * Each added callback has its own separate watcher.
407 * @remarks The specified callback is called only in the main thread.
409 * @param[in] remote_app_id The ID of the remote application
410 * @param[in] remote_port The name of the remote message port
411 * @param[in] trusted_remote_port Indicates whether remote port is trusted
412 * @param[in] unregistered_cb The callback function to be called
413 * when remote port is unregistered
414 * @param[in] user_data The user data to be passed to the callback function
415 * @param[out] watcher_id The ID of the watcher which is monitoring the remote port
416 * unregistration events
417 * @return @c 0 on success,
418 * otherwise a negative error value
419 * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a remote_app_id or @a remote_port
420 * or @a unregistered_cb is NULL
421 * @retval #MESSAGE_PORT_ERROR_OUT_OF_MEMORY Out of memory
422 * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
423 * @see message_port_registration_event_cb()
424 * @see message_port_add_registered_cb()
425 * @see message_port_remove_registration_event_cb()
427 EXPORT_API int message_port_add_unregistered_cb(const char *remote_app_id,
428 const char *remote_port,
429 bool trusted_remote_port,
430 message_port_registration_event_cb unregistered_cb,
436 * @brief Removes the registration/unregistration callback associated with the given watcher.
438 * @param[in] watcher_id The ID of watcher which is monitoring remote port
439 * registration/unregistration events
440 * @return @c 0 on success,
441 * otherwise a negative error value
442 * @retval #MESSAGE_PORT_ERROR_INVALID_PARAMETER The specified @a watcher_id is not correct
443 * @retval #MESSAGE_PORT_ERROR_IO_ERROR Internal I/O error
444 * @see message_port_registration_event_cb()
445 * @see message_port_add_registered_cb()
446 * @see message_port_add_unregistered_cb()
448 EXPORT_API int message_port_remove_registration_event_cb(int watcher_id);
460 #endif /* __TIZEN_APPFW_MESSAGE_PORT_H__ */