Tizen Native API
|
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 *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. |
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.
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 isNULL
.
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 iffalse
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().
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 isNULL
.
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 iffalse
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().
Enumeration Type Documentation
enum message_port_error_e |
Enumeration for error codes of a message port.
- Since :
- 2.3
- Enumerator:
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
- 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, otherwisefalse
- 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, otherwisefalse
- 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
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_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
- Remarks:
- You must releas 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 positiveMESSAGE_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, 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
- 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.
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 positiveMESSAGE_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.
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 | ) |
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
- 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