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_id	The local message port ID returned by message_port_register_local_port()
[in]	remote_app_id	The ID of the remote application that sent this message
[in]	remote_port	The name of the remote message port
[in]	trusted_remote_port	If `true`, the remote port is a trusted port; otherwise if `false`, it is not
[in]	message	The message passed from the remote application
[in]	user_data	The 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_id	The ID of the remote application that sent this message
[in]	remote_port	The name of the remote message port
[in]	trusted_remote_port	Indicates whether remote port is trusted
[in]	user_data	The 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_id	The message port ID returned by message_port_register_trusted_local_port()
[in]	remote_app_id	The ID of the remote application that sent this message
[in]	remote_port	The name of the remote message port
[in]	trusted_remote_port	If `true`, the remote port is a trusted port; otherwise if `false`, it is not
[in]	message	The message passed from the remote application
[in]	user_data	The 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

enum message_port_error_e

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_id	The ID of the remote application
[in]	remote_port	The name of the remote message port
[in]	trusted_remote_port	Indicates whether remote port is trusted
[in]	registered_cb	The callback function to be called when remote port is registered
[in]	user_data	The user data to be passed to the callback function
[out]	watcher_id	The 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_PARAMETER	The specified remote_app_id or remote_port or registered_cb is NULL
MESSAGE_PORT_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGE_PORT_ERROR_IO_ERROR	Internal 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_id	The ID of the remote application
[in]	remote_port	The name of the remote message port
[in]	trusted_remote_port	Indicates whether remote port is trusted
[in]	unregistered_cb	The callback function to be called when remote port is unregistered
[in]	user_data	The user data to be passed to the callback function
[out]	watcher_id	The 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_PARAMETER	The specified remote_app_id or remote_port or unregistered_cb is NULL
MESSAGE_PORT_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGE_PORT_ERROR_IO_ERROR	Internal 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_id	The ID of the remote application
[in]	remote_port	The name of the remote message port
[out]	exist	If `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_NONE	Successful
MESSAGE_PORT_ERROR_INVALID_PARAMETER	The specified remote_app_id or remote_port is NULL
MESSAGE_PORT_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGE_PORT_ERROR_IO_ERROR	Internal 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_id	The ID of the remote application
[in]	remote_port	The name of the remote message port
[out]	exist	If `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_NONE	Successful
MESSAGE_PORT_ERROR_INVALID_PARAMETER	The specified remote_app_id or remote_port is `NULL`
MESSAGE_PORT_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGE_PORT_ERROR_CERTIFICATE_NOT_MATCH	The remote application is not signed with the same certificate
MESSAGE_PORT_ERROR_IO_ERROR	Internal 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_port	The name of the local message port
[in]	callback	The callback function to be called when a message is received
[in]	user_data	The 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_PARAMETER	The specified local_port or callback is NULL
MESSAGE_PORT_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGE_PORT_ERROR_IO_ERROR	Internal 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_port	The name of the trusted local message port
[in]	callback	The callback function to be called when a trusted message is received
[in]	user_data	The 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_PARAMETER	The specified trusted_local_port or callback is NULL
MESSAGE_PORT_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGE_PORT_ERROR_IO_ERROR	Internal I/O error

See also:: message_port_unregister_trusted_local_port()

int message_port_remove_registration_event_cb ( int watcher_id )

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

Since :: 4.0

Parameters:

[in] watcher_id The 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_PARAMETER	The specified watcher_id is not correct
MESSAGE_PORT_ERROR_IO_ERROR	Internal 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_id	The ID of the remote application
[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

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGE_PORT_ERROR_NONE	Successful
MESSAGE_PORT_ERROR_INVALID_PARAMETER	The specified remote_app_id, remote_port or message is NULL
MESSAGE_PORT_ERROR_PORT_NOT_FOUND	The message port of the remote application cannot be found
MESSAGE_PORT_ERROR_MAX_EXCEEDED	The size of message has exceeded the maximum limit
MESSAGE_PORT_ERROR_RESOURCE_UNAVAILABLE	Resource temporarily unavailable
MESSAGE_PORT_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGE_PORT_ERROR_IO_ERROR	Internal 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_id	The ID of the remote application
[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 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_NONE	Successful
MESSAGE_PORT_ERROR_INVALID_PARAMETER	The specified remote_app_id, remote_port or message is `NULL` and The specified local_port_id is not positive
MESSAGE_PORT_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGE_PORT_ERROR_PORT_NOT_FOUND	The port of the local or remote application cannot be found
MESSAGE_PORT_ERROR_MAX_EXCEEDED	The size of the message has exceeded the maximum limit
MESSAGE_PORT_ERROR_IO_ERROR	Internal 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_id	The ID of the remote application
[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

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGE_PORT_ERROR_NONE	Successful
MESSAGE_PORT_ERROR_INVALID_PARAMETER	The specified remote_app_id, remote_port or message is `NULL`
MESSAGE_PORT_ERROR_PORT_NOT_FOUND	The message port of the remote application cannot be 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
MESSAGE_PORT_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGE_PORT_ERROR_IO_ERROR	Internal 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_id	The ID of the remote application
[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 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_NONE	Successful
MESSAGE_PORT_ERROR_INVALID_PARAMETER	The specified remote_app_id, remote_port or message is `NULL` and specified local_port_id is not positive
MESSAGE_PORT_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGE_PORT_ERROR_PORT_NOT_FOUND	The port of the local or remote application cannot be 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_IO_ERROR	Internal 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_id The local message port ID

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGE_PORT_ERROR_NONE	Successful
MESSAGE_PORT_ERROR_INVALID_PARAMETER	The specified local_port_id is not positive
MESSAGE_PORT_ERROR_PORT_NOT_FOUND	The specified local_port_id cannot be found
MESSAGE_PORT_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGE_PORT_ERROR_IO_ERROR	Internal 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_id The trusted local message port ID

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGE_PORT_ERROR_NONE	Successful
MESSAGE_PORT_ERROR_INVALID_PARAMETER	The specified trusted_local_port_id is not positive
MESSAGE_PORT_ERROR_PORT_NOT_FOUND	The specified trusted_local_port_id cannot be found
MESSAGE_PORT_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGE_PORT_ERROR_IO_ERROR	Internal I/O error

See also:: message_port_register_trusted_local_port()

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation