Tizen Native API

The Message Port API provides functions to send and receive messages between applications.

Required Header

#include <message_port.h>

Overview

The Message Port API provides functions for passing messages between applications. An application should register its own local port to receive messages from remote applications. If a remote application sends a message, the registered callback function of the local port is called.
The trusted message-port API allows communications between applications that are signed by the same developer (author) certificate.

Functions

int message_port_register_local_port (const char *local_port, message_port_message_cb callback, void *user_data)
 Registers the local message port.
int message_port_register_trusted_local_port (const char *trusted_local_port, message_port_trusted_message_cb callback, void *user_data)
 Registers the trusted local message port.
int message_port_unregister_local_port (int local_port_id)
 Unregisters the local message port.
int message_port_unregister_trusted_local_port (int trusted_local_port_id)
 Registers the trusted local message port.
int message_port_check_remote_port (const char *remote_app_id, const char *remote_port, bool *exist)
 Checks whether the message port of a remote application is registered.
int message_port_check_trusted_remote_port (const char *remote_app_id, const char *remote_port, bool *exist)
 Checks whether the trusted message port of a remote application is registered.
int message_port_send_message (const char *remote_app_id, const char *remote_port, bundle *message)
 Sends a message to the message port of a remote application.
int message_port_send_trusted_message (const char *remote_app_id, const char *remote_port, bundle *message)
 Sends a trusted message to the message port of a remote application.
int message_port_send_message_with_local_port (const char *remote_app_id, const char *remote_port, bundle *message, int local_port_id)
 Sends a message with local port information to the message port of a remote application.
int message_port_send_trusted_message_with_local_port (const char *remote_app_id, const char *remote_port, bundle *message, int local_port_id)
 Sends a trusted message with local port information to the message port of a remote application.

Typedefs

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)
 Called when a message is received.
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)
 Called when a trusted message is received.

Typedef Documentation

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)

Called when a message is received.

The function is called when a message is received from the remote application.

Since :
2.3.1
Remarks:
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 NULL.
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.
Parameters:
[in]local_port_idThe local message port ID returned by message_port_register_local_port()
[in]remote_app_idThe ID of the remote application that sent this message
[in]remote_portThe name of the remote message port
[in]trusted_remote_portIf true the remote port is a trusted port, otherwise if false it is not
[in]messageThe message passed from the remote application
[in]user_dataThe user data passed from the register function
Precondition:
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 also:
message_port_register_local_port()
message_port_unregister_local_port()
message_port_send_message()
message_port_send_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)

Called when a trusted message is received.

This function is called when a trusted message is received from the remote application.

Since :
2.3.1
Remarks:
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 NULL.
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.
Parameters:
[in]trusted_local_port_idThe message port ID returned by message_port_register_trusted_local_port()
[in]remote_app_idThe ID of the remote application that sent this message
[in]remote_portThe name of the remote message port
[in]trusted_remote_portIf true the remote port is a trusted port, otherwise if false it is not
[in]messageThe message passed from the remote application
[in]user_dataThe user data passed from the register function
Precondition:
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 also:
message_port_register_trusted_local_port()
message_port_unregister_trusted_local_port()
message_port_send_trusted_message()
message_port_send_trusted_message_with_local_port()

Enumeration Type Documentation

Enumeration for error codes of a message port.

Since :
2.3.1
Enumerator:
MESSAGE_PORT_ERROR_NONE 

Successful

MESSAGE_PORT_ERROR_IO_ERROR 

Internal I/O error

MESSAGE_PORT_ERROR_OUT_OF_MEMORY 

Out of memory

MESSAGE_PORT_ERROR_INVALID_PARAMETER 

Invalid parameter

MESSAGE_PORT_ERROR_PORT_NOT_FOUND 

The message port of the remote application is not found

MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH 

The remote application is not signed with the same certificate

MESSAGE_PORT_ERROR_MAX_EXCEEDED 

The size of the message has exceeded the maximum limit

MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLE 

Resource is temporarily unavailable


Function Documentation

int message_port_check_remote_port ( const char *  remote_app_id,
const char *  remote_port,
bool *  exist 
)

Checks whether the message port of a remote application is registered.

Since :
2.3.1
Remarks:
If this function returns a negative error value, the out parameter exist will not be changed.
Parameters:
[in]remote_app_idThe ID of the remote application
[in]remote_portThe name of the remote message port
[out]existIf true the message port of the remote application exists, otherwise false
Returns:
0 on success, otherwise a negative error value
Return values:
MESSAGE_PORT_ERROR_NONESuccessful
MESSAGE_PORT_ERROR_INVALID_PARAMETERThe specified remote_app_id or remote_port is NULL
MESSAGE_PORT_ERROR_OUT_OF_MEMORYOut of memory
MESSAGE_PORT_ERROR_IO_ERRORInternal I/O error
int message_port_check_trusted_remote_port ( const char *  remote_app_id,
const char *  remote_port,
bool *  exist 
)

Checks whether the trusted message port of a remote application is registered.

Since :
2.3.1
Remarks:
If this function returns a negative error value, the out parameter exist will not be changed.
Parameters:
[in]remote_app_idThe ID of the remote application
[in]remote_portThe name of the remote message port
[out]existIf true the message port of the remote application exists, otherwise false
Returns:
0 on success, otherwise a negative error value
Return values:
MESSAGE_PORT_ERROR_NONESuccessful
MESSAGE_PORT_ERROR_INVALID_PARAMETERThe specified remote_app_id or remote_port is NULL
MESSAGE_PORT_ERROR_OUT_OF_MEMORYOut of memory
MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCHThe remote application is not signed with the same certificate
MESSAGE_PORT_ERROR_IO_ERRORInternal I/O error
int message_port_register_local_port ( const char *  local_port,
message_port_message_cb  callback,
void *  user_data 
)

Registers the local message port.

If the message port name is already registered, the previous local message port ID returns and the callback function is changed.
Multiple message ports can be registered.

Since :
2.3.1
Remarks:
The specified callback is called only in the main thread.
Parameters:
[in]local_portThe name of the local message port
[in]callbackThe callback function to be called when a message is received
[in]user_dataThe user data to be passed to the callback function
Returns:
A local message port ID on success, otherwise a negative error value
Return values:
MESSAGE_PORT_ERROR_INVALID_PARAMETERThe specified local_port or callback is NULL
MESSAGE_PORT_ERROR_OUT_OF_MEMORYOut of memory
MESSAGE_PORT_ERROR_IO_ERRORInternal I/O error
See also:
message_port_unregister_local_port()
int message_port_register_trusted_local_port ( const char *  trusted_local_port,
message_port_trusted_message_cb  callback,
void *  user_data 
)

Registers the trusted local message port.

If the message port name is already registered, the previous local message port ID returns and the callback function is changed.
It allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.
Multiple message ports can be registered.

Since :
2.3.1
Remarks:
The specified callback is called only in the main thread.
Parameters:
[in]trusted_local_portThe name of the trusted local message port
[in]callbackThe callback function to be called when a trusted message is received
[in]user_dataThe user data to be passed to the callback function
Returns:
A trusted local message port ID on success, otherwise a negative error value
Return values:
MESSAGE_PORT_ERROR_INVALID_PARAMETERThe specified trusted_local_port or callback is NULL
MESSAGE_PORT_ERROR_OUT_OF_MEMORYOut of memory
MESSAGE_PORT_ERROR_IO_ERRORInternal I/O error
See also:
message_port_unregister_trusted_local_port()
int message_port_send_message ( const char *  remote_app_id,
const char *  remote_port,
bundle message 
)

Sends a message to the message port of a remote application.

Since :
2.3.1
Remarks:
message must be released with bundle_free() after sending the message.
Parameters:
[in]remote_app_idThe ID of the remote application
[in]remote_portThe name of the remote message port
[in]messageThe message to be passed to the remote application, the recommended message size is under 4KB
Returns:
0 on success, otherwise a negative error value
Return values:
MESSAGE_PORT_ERROR_NONESuccessful
MESSAGE_PORT_ERROR_INVALID_PARAMETERThe specified remote_app_id, remote_port or message is NULL
MESSAGE_PORT_ERROR_PORT_NOT_FOUNDThe message port of the remote application cannot be found
MESSAGE_PORT_ERROR_MAX_EXCEEDEDThe size of message has exceeded the maximum limit
MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLEResource temporarily unavailable
MESSAGE_PORT_ERROR_OUT_OF_MEMORYOut of memory
MESSAGE_PORT_ERROR_IO_ERRORInternal I/O error
Postcondition:
It invokes message_port_message_cb() on the remote application.
See also:
message_port_message_cb()
message_port_register_local_port()
message_port_unregister_local_port()
 #include <message_port.h>

 bundle *b = bundle_create();
 bundle_add_str(b, "key1", "value1");
 bundle_add_str(b, "key2", "value2");

 int ret = message_port_send_message("0123456789.BasicApp", "BasicAppPort", b);

 bundle_free(b);
int message_port_send_message_with_local_port ( const char *  remote_app_id,
const char *  remote_port,
bundle message,
int  local_port_id 
)

Sends a message with local port information to the message port of a remote application.

This method is used for bidirectional communication.

Since :
2.3.1
Remarks:
You must releas message using bundle_free() after sending the message.
Parameters:
[in]remote_app_idThe ID of the remote application
[in]remote_portThe name of the remote message port
[in]messageThe message to be passed to the remote application, the recommended message size is under 4KB
[in]local_port_idThe message port ID returned by message_port_register_local_port() or message_port_register_trusted_local_port()
Returns:
0 on success, otherwise a negative error value
Return values:
MESSAGE_PORT_ERROR_NONESuccessful
MESSAGE_PORT_ERROR_INVALID_PARAMETERThe specified remote_app_id, remote_port or message is NULL and The specified local_port_id is not positive
MESSAGE_PORT_ERROR_OUT_OF_MEMORYOut of memory
MESSAGE_PORT_ERROR_PORT_NOT_FOUNDThe port of the local or remote application cannot be found
MESSAGE_PORT_ERROR_MAX_EXCEEDEDThe size of the message has exceeded the maximum limit
MESSAGE_PORT_ERROR_IO_ERRORInternal I/O error
Postcondition:
It invokes message_port_message_cb() on the remote application.
See also:
message_port_message_cb()
message_port_register_local_port()
message_port_unregister_local_port()
 #include <message_port.h>

 static void
 message_port_receive_cb(int local_port_id, const char *remote_app_id, const char *remote_port, bool trusted_remote_port, bundle *message, void *user_data)
 {
 }

 int main(int argc, char *argv[])
 {
   bundle *b = bundle_create();
   bundle_add_str(b, "key1", "value1");
   bundle_add_str(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);
 }
int message_port_send_trusted_message ( const char *  remote_app_id,
const char *  remote_port,
bundle message 
)

Sends a trusted message to the message port of a remote application.

This method allows communication only if the applications are signed with the same certificate which is uniquely assigned to the developer.

Since :
2.3.1
Remarks:
You must release message using bundle_free() after sending the message.
Parameters:
[in]remote_app_idThe ID of the remote application
[in]remote_portThe name of the remote message port
[in]messageThe message to be passed to the remote application, the recommended message size is under 4KB
Returns:
0 on success, otherwise a negative error value
Return values:
MESSAGE_PORT_ERROR_NONESuccessful
MESSAGE_PORT_ERROR_INVALID_PARAMETERThe specified remote_app_id, remote_port or message is NULL
MESSAGE_PORT_ERROR_PORT_NOT_FOUNDThe message port of the remote application cannot be found
MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCHThe remote application is not signed with the same certificate
MESSAGE_PORT_ERROR_MAX_EXCEEDEDThe size of the message has exceeded the maximum limit
MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLEResource is temporarily unavailable
MESSAGE_PORT_ERROR_OUT_OF_MEMORYOut of memory
MESSAGE_PORT_ERROR_IO_ERRORInternal I/O error
Postcondition:
It invokes message_port_trusted_message_cb() on the remote application.
See also:
message_port_trusted_message_cb()
message_port_register_trusted_local_port()
message_port_unregister_trusted_local_port()
int message_port_send_trusted_message_with_local_port ( const char *  remote_app_id,
const char *  remote_port,
bundle message,
int  local_port_id 
)

Sends a trusted message with local port information to the message port of a remote application.

This method is used for bidirectional communication.
It allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.

Since :
2.3.1
Remarks:
You muse release message using bundle_free() after sending the message.
Parameters:
[in]remote_app_idThe ID of the remote application
[in]remote_portThe name of the remote message port
[in]messageThe message to be passed to the remote application, the recommended message size is under 4KB
[in]local_port_idThe message port ID returned by message_port_register_local_port() or message_port_register_trusted_local_port()
Returns:
0 on success, otherwise a negative error value
Return values:
MESSAGE_PORT_ERROR_NONESuccessful
MESSAGE_PORT_ERROR_INVALID_PARAMETERThe specified remote_app_id, remote_port or message is NULL and specified local_port_id is not positive
MESSAGE_PORT_ERROR_OUT_OF_MEMORYOut of memory
MESSAGE_PORT_ERROR_PORT_NOT_FOUNDThe port of the local or remote application cannot be found.
MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCHThe remote application is not signed with the same certificate.
MESSAGE_PORT_ERROR_MAX_EXCEEDEDThe size of the message has exceeded the maximum limit.
MESSAGE_PORT_ERROR_IO_ERRORInternal I/O error
Postcondition:
It invokes message_port_trusted_message_cb() on the remote application.
See also:
message_port_trusted_message_cb()
message_port_register_trusted_local_port()
message_port_unregister_trusted_local_port()
int message_port_unregister_local_port ( int  local_port_id)

Unregisters the local message port.

This method unregisters the callback function with the specified local port ID.

Since :
2.3.1
Parameters:
[in]local_port_idThe local message port ID
Returns:
0 on success, otherwise a negative error value
Return values:
MESSAGE_PORT_ERROR_NONESuccessful
MESSAGE_PORT_ERROR_INVALID_PARAMETERThe specified local_port_id is not positive
MESSAGE_PORT_ERROR_PORT_NOT_FOUNDThe specified local_port_id cannot be found
MESSAGE_PORT_ERROR_OUT_OF_MEMORYOut of memory
MESSAGE_PORT_ERROR_IO_ERRORInternal I/O error
See also:
message_port_register_local_port()
int message_port_unregister_trusted_local_port ( int  trusted_local_port_id)

Registers the trusted local message port.

This method unregisters the callback function with the specified local port ID.
It allows communications only if the applications are signed with the same certificate which is uniquely assigned to the developer.

Since :
2.3.1
Parameters:
[in]trusted_local_port_idThe trusted local message port ID
Returns:
0 on success, otherwise a negative error value
Return values:
MESSAGE_PORT_ERROR_NONESuccessful
MESSAGE_PORT_ERROR_INVALID_PARAMETERThe specified trusted_local_port_id is not positive
MESSAGE_PORT_ERROR_PORT_NOT_FOUNDThe specified trusted_local_port_id cannot be found
MESSAGE_PORT_ERROR_OUT_OF_MEMORYOut of memory
MESSAGE_PORT_ERROR_IO_ERRORInternal I/O error
See also:
message_port_register_trusted_local_port()