Tizen(Headless) Native API  6.0

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)
 Unregisters 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.
int message_port_add_registered_cb (const char *remote_app_id, const char *remote_port, bool trusted_remote_port, message_port_registration_event_cb registered_cb, void *user_data, int *watcher_id)
 Adds a callback called when a remote port is registered.
int message_port_add_unregistered_cb (const char *remote_app_id, const char *remote_port, bool trusted_remote_port, message_port_registration_event_cb unregistered_cb, void *user_data, int *watcher_id)
 Adds a callback called when a remote port is unregistered.
int message_port_remove_registration_event_cb (int watcher_id)
 Removes the registration/unregistration callback associated with the given watcher.

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 *message, 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 void(* message_port_registration_event_cb )(const char *remote_app_id, const char *remote_port, bool trusted_remote_port, void *user_data)
 Called when a remote port is registered or unregistered.

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 *message, 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
Remarks:
message is automatically freed by framework when callback returned, you can keep message using bundle_dup()
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_registration_event_cb)(const char *remote_app_id, const char *remote_port, bool trusted_remote_port, void *user_data)

Called when a remote port is registered or unregistered.

The function is called when a remote port is registered or unregistered from the remote application.

Since :
4.0
Remarks:
remote_app_id and remote_port can be used until message_port_remove_registration_event_cb() is called for the watcher which reported the event.
Parameters:
[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_portIndicates whether remote port is trusted
[in]user_dataThe user data passed from the register function
Precondition:
Called when a remote port is registered or unregistered if you add it using message_port_add_registered_cb() or message_port_add_unregistered_cb() respectively.
See also:
message_port_add_registered_cb()
message_port_add_unregistered_cb()
message_port_remove_registration_event_cb()
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
Remarks:
You can keep message using bundle_dup().
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
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_add_registered_cb ( const char *  remote_app_id,
const char *  remote_port,
bool  trusted_remote_port,
message_port_registration_event_cb  registered_cb,
void *  user_data,
int *  watcher_id 
)

Adds a callback called when a remote port is registered.

When remote port is registered, registered_cb function is called. Each added callback has its own separate watcher.

Since :
4.0
Remarks:
The specified callback is called only in the main thread.
Parameters:
[in]remote_app_idThe ID of the remote application
[in]remote_portThe name of the remote message port
[in]trusted_remote_portIndicates whether remote port is trusted
[in]registered_cbThe callback function to be called when remote port is registered
[in]user_dataThe user data to be passed to the callback function
[out]watcher_idThe ID of the watcher which is monitoring the remote port registration events
Returns:
0 on success, otherwise a negative error value
Return values:
MESSAGE_PORT_ERROR_INVALID_PARAMETERThe specified remote_app_id or remote_port or registered_cb is NULL
MESSAGE_PORT_ERROR_OUT_OF_MEMORYOut of memory
MESSAGE_PORT_ERROR_IO_ERRORInternal I/O error
See also:
message_port_registration_event_cb()
message_port_add_unregistered_cb()
message_port_remove_registration_event_cb()
int message_port_add_unregistered_cb ( const char *  remote_app_id,
const char *  remote_port,
bool  trusted_remote_port,
message_port_registration_event_cb  unregistered_cb,
void *  user_data,
int *  watcher_id 
)

Adds a callback called when a remote port is unregistered.

When the remote port is unregistered, unregistered_cb function is called. Each added callback has its own separate watcher.

Since :
4.0
Remarks:
The specified callback is called only in the main thread.
Parameters:
[in]remote_app_idThe ID of the remote application
[in]remote_portThe name of the remote message port
[in]trusted_remote_portIndicates whether remote port is trusted
[in]unregistered_cbThe callback function to be called when remote port is unregistered
[in]user_dataThe user data to be passed to the callback function
[out]watcher_idThe ID of the watcher which is monitoring the remote port unregistration events
Returns:
0 on success, otherwise a negative error value
Return values:
MESSAGE_PORT_ERROR_INVALID_PARAMETERThe specified remote_app_id or remote_port or unregistered_cb is NULL
MESSAGE_PORT_ERROR_OUT_OF_MEMORYOut of memory
MESSAGE_PORT_ERROR_IO_ERRORInternal I/O error
See also:
message_port_registration_event_cb()
message_port_add_registered_cb()
message_port_remove_registration_event_cb()
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
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
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
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
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()

Removes the registration/unregistration callback associated with the given watcher.

Since :
4.0
Parameters:
[in]watcher_idThe ID of watcher which is monitoring remote port registration/unregistration events
Returns:
0 on success, otherwise a negative error value
Return values:
MESSAGE_PORT_ERROR_INVALID_PARAMETERThe specified watcher_id is not correct
MESSAGE_PORT_ERROR_IO_ERRORInternal I/O error
See also:
message_port_registration_event_cb()
message_port_add_registered_cb()
message_port_add_unregistered_cb()
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
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(b, "key1", "value1");
 bundle_add(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
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
[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, 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);
 }
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
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
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
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)

Unregisters 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
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()