Message Port: Passing Messages Between Applications
This tutorial demonstrates how you can register, unregister, and check the message port, and send messages through the message port.
Warm-up
Become familiar with the Message Port API basics by learning about:
-
Initializing Message Port Communication
Initialize the message port communication for use.
-
Using Uni-directional Message Port Communication
Send and receive messages using uni-directional message port communication between Tizen native applications.
-
Using Bi-directional Message Port Communication
Send and receive messages using bi-directional message port communication between Tizen native applications.
-
Using Trusted Message Port Communication
Send and receive messages using trusted message port communication between Tizen native applications.
Initializing Message Port Communication
To initialize message port communication:
-
To use the functions and data types of the Message Port API (in mobile and wearable applications), include the <message_port.h> header file in your application:
#include <message_port.h>
-
You need 2 applications to communicate with each other through the message port.
To use trusted message port communication, create an author certificate, register the certificate to the IDE, and grant permissions by the application certificate in the manifest editor.
Using Uni-directional Message Port Communication
To send a message from Application 1 to Application 2 using the Message Port API:
Figure: Uni-directional message port communication
-
Register a local port in Application 2.
To register the local port, call the message_port_register_local_port() function.
int message_port_register_local_port(const char* local_port, message_port_message_cb callback, void* user_data)
The function requires 2 parameters:
- [in] local_port: The name of the local message port
- [in] callback: The callback function to be called when a message is received
- Return: A local message port ID on success, otherwise a negative error value
Implement the following codes in Application 2. Implement the message_port_cb() callback function for the message_port_register_local_port() function.
void message_port_cb(int local_port_id, const char *remote_app_id, const char *remote_port, bool trusted_remote_port, bundle *message, void *user_data) { char *command = NULL; char *data = NULL; bundle_get_str(message, "command", &command); bundle_get_str(message, "data", &data); dlog_print(DLOG_INFO, TAG, "Message from %s, command: %s data: %s", remote_app_id, command, data); }
Call the message_port_register_local_port() function.
int port_id = message_port_register_local_port(local_port, message_port_cb, NULL); if (port_id < 0) { dlog_print(DLOG_ERROR, LOG_TAG, "Port register error : %d", port_id); } else { dlog_print(DLOG_INFO, LOG_TAG, "port_id : %d", port_id); }
-
Check the remote port in Application 1:
To check the remote port, call the message_port_check_remote_port() function.
int message_port_check_remote_port(const char* remote_app_id, const char* remote_port, bool* exist)
The function requires 3 parameters:
- [in] remote_app_id: The name of the local message port
- [in] remote_port: The name of the remote message port
- [out] exist: true if the message port of the remote application exists, otherwise false
- Return: 0 on success, otherwise a negative error value
Implement the following codes in Application 1:
bool test_check_remote_port() { int ret; bool found; ret = message_port_check_remote_port (remote_app_id, remote_port, &found); if (ret != MESSAGE_PORT_ERROR_NONE) { dlog_print(DLOG_ERROR, TAG, "message_port_check_remote_port error : %d", ret); } return found; }
-
Send a message in Application 1.
To send a message, call the message_port_send_message() function:
int message_port_send_message(const char* remote_app_id, const char* remote_port, bundle* message)
The function requires 3 parameters:
- [in] remote_app_id: The name of the local message port
- [in] remote_port: The name of the remote message port
- [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
void send_message(void) { int ret; bundle *b = bundle_create (); bundle_add_str (b, "command", "begin"); bundle_add_str (b, "data", "dummy"); ret = message_port_send_message (remote_app_id, remote_port, b); if (ret != MESSAGE_PORT_ERROR_NONE) { dlog_print(DLOG_ERROR, TAG, "message_port_check_remote_port error : %d", ret); } else { dlog_print(DLOG_INFO, TAG, "Send message done"); } bundle_free (b); }
Using Bi-directional Message Port Communication
To send a message from Application 1 to Application 2, and from Application 2 to Application 1:
Figure: Bi-directional message port communication
-
Implement the response logic.
void message_port_cb(int local_port_id, const char *remote_app_id, const char *remote_port, bool trusted_remote_port, bundle *message, void *user_data) { int ret; char *command = NULL; char *data = NULL; bundle_get_str(message, "command", &command); bundle_get_str(message, "data", &data); // Callback dlog_print(DLOG_INFO, TAG, "Message from %s, command: %s data: %s", remote_app_id, command, data); bundle *reply = bundle_create (); bundle_add_str (reply, "result", "GOT_IT"); ret = message_port_send_message (remote_app_id, remote_port, reply); bundle_free (reply); if (ret != MESSAGE_PORT_ERROR_NONE) { dlog_print(DLOG_ERROR, TAG, "Port send message error : %d", ret); } }
-
Register the local port in Application 1.
void message_port_cb(int local_port_id, const char *remote_app_id, const char *remote_port, bool trusted_remote_port, bundle *message, void *user_data) { char *result = NULL; bundle_get_str(message, "result", &result); dlog_print(DLOG_INFO, TAG, "Message from %s, result: %s ", remote_app_id, result); }
Call the message_port_register_local_port() function.
int local_port_id = message_port_register_local_port(local_port, message_port_cb); if (local_port_id < 0) { dlog_print(DLOG_ERROR, TAG, "Port register error : %d", local_port_id); } else { dlog_print(DLOG_INFO, TAG, "port_id : %d", port_id); }
-
Send a message with local port information.
To get a response from the receiver, local port information has to be sent to the receiver when the message was delivered. To do this, call the message_port_send_message_with_local_port() function.
The function requires 4 parameters:
- [in] remote_app_id: The name of the local message port
- [in] remote_port: The name of the remote message port
- [in] message: The message to be passed to the remote application, the recommended message size is under 4KB
- [in] local_port_id: The message port ID returned by the message_port_register_local_port() or message_port_register_trusted_local_port() function
- Return: 0 on success, otherwise a negative error value
Implement the following codes in Application 1:
void send_message_with_local_port(int local_port_id) { int ret; bundle *b = bundle_create (); bundle_add_str (b, "command", "begin"); bundle_add_str (b, "data", "dummy"); ret = message_port_send_message_with_local_port(remote_app_id, remote_port, b, local_port_id); if (ret != MESSAGE_PORT_ERROR_NONE) { dlog_print(DLOG_ERROR, TAG, "message_port_send_message_with_local_port error : %d", ret); } else { dlog_print(DLOG_INFO, TAG, "Send message done"); } bundle_free (b); }
Call the send_message_with_local_port() function:
if (test_check_remote_port()) { dlog_print(DLOG_INFO, TAG, "Remote port check success."); send_message_with_local_port(local_port_id); }
Using Trusted Message Port Communication
To use the trusted message port communication:
Figure: Trusted uni-directional message port communication
Create the author certificate, register the created certificate to the IDE, and give permissions by the application certificate in the manifest editor.
During trusted message port communication, only applications signed with the same certificate can communicate with each other.
The usage is similar to the normal Message Port API implementation. However, you must use trusted functions instead of normal functions.
- Use the message_port_check_trusted_remote_port() function instead of the message_port_check_remote_port() function.
- Use the message_port_send_trusted_message() function instead of the message_port_send_message() function.
- Use the message_port_register_trusted_local_port() function instead of the message_port_register_local_port() function.