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

Required Header

#include <rpc-port.h>

Overview

The RPC Port API provides functions for passing messages between applications. Applications can read and write data by using rpc-port.

Functions
int	rpc_port_read (rpc_port_h h, void *buf, unsigned int size)
	Reads data from an RPC port.
int	rpc_port_write (rpc_port_h h, const void *buf, unsigned int size)
	Writes data to an RPC port.
int	rpc_port_proxy_create (rpc_port_proxy_h *h)
	Creates a rpc port proxy handle.
int	rpc_port_proxy_destroy (rpc_port_proxy_h h)
	Destroys a rpc port proxy handle.
int	rpc_port_proxy_connect (rpc_port_proxy_h h, const char appid, const char port)
	Connects to port of appid.
int	rpc_port_proxy_add_connected_event_cb (rpc_port_proxy_h h, rpc_port_proxy_connected_event_cb cb, void *user_data)
	Adds a proxy connected callback.
int	rpc_port_proxy_add_disconnected_event_cb (rpc_port_proxy_h h, rpc_port_proxy_disconnected_event_cb cb, void *user_data)
	Adds a proxy disconnected callback.
int	rpc_port_proxy_add_rejected_event_cb (rpc_port_proxy_h h, rpc_port_proxy_rejected_event_cb cb, void *user_data)
	Adds a proxy rejected callback.
int	rpc_port_proxy_add_received_event_cb (rpc_port_proxy_h h, rpc_port_proxy_received_event_cb cb, void *user_data)
	Adds a proxy received callback.
int	rpc_port_proxy_get_port (rpc_port_proxy_h h, rpc_port_port_type_e type, rpc_port_h *port)
	Gets a port from proxy handle.
int	rpc_port_stub_create (rpc_port_stub_h h, const char port_name)
	Creates a rpc port stub handle.
int	rpc_port_stub_destroy (rpc_port_stub_h h)
	Destroys a rpc port stub handle.
int	rpc_port_stub_listen (rpc_port_stub_h h)
	Listens to the requests for connections.
int	rpc_port_stub_add_privilege (rpc_port_stub_h h, const char *privilege)
	Adds a privilege to the stub.
int	rpc_port_stub_set_trusted (rpc_port_stub_h h, const bool trusted)
	Sets trusted to the stub.
int	rpc_port_stub_add_connected_event_cb (rpc_port_stub_h h, rpc_port_stub_connected_event_cb cb, void *user_data)
	Adds a stub connected callback.
int	rpc_port_stub_add_disconnected_event_cb (rpc_port_stub_h h, rpc_port_stub_disconnected_event_cb cb, void *user_data)
	Adds a stub disconnected callback.
int	rpc_port_stub_add_received_event_cb (rpc_port_stub_h h, rpc_port_stub_received_event_cb cb, void *user_data)
	Adds a stub received callback.
int	rpc_port_stub_get_port (rpc_port_stub_h h, rpc_port_port_type_e type, const char instance, rpc_port_h port)
	Gets a port from stub handle.
int	rpc_port_proxy_connect_sync (rpc_port_proxy_h h, const char appid, const char port_name)
	Connects to port_name of appid synchronously.
int	rpc_port_set_private_sharing_array (rpc_port_h port, const char *paths[], unsigned int size)
	Sets the paths of private sharing files.
int	rpc_port_set_private_sharing (rpc_port_h port, const char *path)
	Sets the path of the private sharing file.
int	rpc_port_unset_private_sharing (rpc_port_h port)
	Unsets the private sharing.
int	rpc_port_disconnect (rpc_port_h port)
	Disconnects the port.
Typedefs
typedef void *	rpc_port_h
	The rpc port handle.
typedef void(*	rpc_port_proxy_connected_event_cb )(const char receiver, const char port_name, rpc_port_h port, void *user_data)
	Called when the proxy is connected.
typedef void(*	rpc_port_proxy_disconnected_event_cb )(const char receiver, const char port_name, void *user_data)
	Called when the proxy is disconnected.
typedef void(*	rpc_port_proxy_rejected_event_cb )(const char receiver, const char port_name, void *user_data)
	Called when the proxy is rejected.
typedef void(*	rpc_port_proxy_received_event_cb )(const char receiver, const char port_name, void *user_data)
	Called when the proxy received data.
typedef void *	rpc_port_proxy_h
	The rpc port proxy handle.
typedef void *	rpc_port_stub_h
	The rpc port stub handle.
typedef void(*	rpc_port_stub_connected_event_cb )(const char sender, const char instance, void *user_data)
	Called when the proxy is connected with stub.
typedef void(*	rpc_port_stub_disconnected_event_cb )(const char sender, const char instance, void *user_data)
	Called when the proxy is disconnected from stub.
typedef int(*	rpc_port_stub_received_event_cb )(const char sender, const char instance, rpc_port_h port, void *user_data)
	Called when the stub received data from proxy.

Typedef Documentation

typedef void* rpc_port_h

The rpc port handle.

Since :: 5.0

typedef void(* rpc_port_proxy_connected_event_cb)(const char *receiver, const char *port_name, rpc_port_h port, void *user_data)

Called when the proxy is connected.

The function is called when the proxy is connected with stub by port.

Since :: 5.0

Parameters:

[in]	receiver	The target stub app id
[in]	port_name	The name of the port
[in]	port	The rpc port handle for reading and writing
[in]	user_data	The user data passed from the register function

typedef void(* rpc_port_proxy_disconnected_event_cb)(const char *receiver, const char *port_name, void *user_data)

Called when the proxy is disconnected.

The function is called when the proxy is disconnected from stub.

Since :: 5.0

Parameters:

[in]	receiver	The target stub app id
[in]	port_name	The name of the port
[in]	user_data	The user data passed from the register function

typedef void* rpc_port_proxy_h

The rpc port proxy handle.

Since :: 5.0

typedef void(* rpc_port_proxy_received_event_cb)(const char *receiver, const char *port_name, void *user_data)

Called when the proxy received data.

The function is called when the proxy received data from stub.

Since :: 5.0

Parameters:

[in]	receiver	The target stub app id
[in]	port_name	The name of the port
[in]	user_data	The user data passed from the register function

typedef void(* rpc_port_proxy_rejected_event_cb)(const char *receiver, const char *port_name, void *user_data)

Called when the proxy is rejected.

The function is called when the proxy is rejected to connect stub.

Since :: 5.0

Parameters:

[in]	receiver	The target stub app id
[in]	port_name	The name of the port
[in]	user_data	The user data passed from the register function

typedef void(* rpc_port_stub_connected_event_cb)(const char *sender, const char *instance, void *user_data)

Called when the proxy is connected with stub.

The function is called when the proxy is connected with stub. When a proxy connects to stub several times with new port, you can handle each request by using instance.

Since :: 5.0

Parameters:

[in]	sender	The target proxy app id
[in]	instance	The information of the request
[in]	user_data	The user data passed from the register function

typedef void(* rpc_port_stub_disconnected_event_cb)(const char *sender, const char *instance, void *user_data)

Called when the proxy is disconnected from stub.

The function is called when the proxy is disconnected from stub. When a proxy is disconnected, you can check the request by using instance.

Since :: 5.0

Parameters:

[in]	sender	The target proxy app id
[in]	instance	The information of the request
[in]	user_data	The user data passed from the register function

typedef void* rpc_port_stub_h

The rpc port stub handle.

Since :: 5.0

typedef int(* rpc_port_stub_received_event_cb)(const char *sender, const char *instance, rpc_port_h port, void *user_data)

Called when the stub received data from proxy.

The function is called when the stub received data from stub. When a stub received data from several ports, you can handle each request by using instance. If the function returns non zero value, the stub is disconnected.

Since :: 5.0

Parameters:

[in]	sender	The target proxy app id
[in]	instance	The information of the request
[in]	port	The rpc port handle for reading and writing
[in]	user_data	The user data passed from the register function

Returns:: zero to continue receive data with the sender, otherwise nonzero to disconnect from the port

Enumeration Type Documentation

enum rpc_port_error_e

Enumeration for error codes of a rpc port.

Since :: 5.0

Enumerator:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_IO_ERROR	Internal I/O error
RPC_PORT_ERROR_OUT_OF_MEMORY	Out of memory
RPC_PORT_ERROR_INVALID_PARAMETER	Invalid parameter
RPC_PORT_ERROR_PERMISSION_DENIED	Permission denied

enum rpc_port_port_type_e

Enumeration for types of communication channels.

Since :: 5.0

Enumerator:

RPC_PORT_PORT_MAIN	Main channel
RPC_PORT_PORT_CALLBACK	The channel for callbacks

Function Documentation

int rpc_port_disconnect ( rpc_port_h port )

Disconnects the port.

Since :: 6.5

Parameters:

[in] port The rpc port handle

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	Invalid parameter

int rpc_port_proxy_add_connected_event_cb	(	rpc_port_proxy_h	h,
		rpc_port_proxy_connected_event_cb	cb,
		void *	user_data
	)

Adds a proxy connected callback.

Since :: 5.0

Parameters:

[in]	h	The rpc port proxy handle
[in]	cb	The callback function to be called when proxy is connected
[in]	user_data	The user data to be passed to the rpc_port_proxy_connected_event_cb() function

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL

int rpc_port_proxy_add_disconnected_event_cb	(	rpc_port_proxy_h	h,
		rpc_port_proxy_disconnected_event_cb	cb,
		void *	user_data
	)

Adds a proxy disconnected callback.

Since :: 5.0

Parameters:

[in]	h	The rpc port proxy handle
[in]	cb	The callback function to be called when proxy is disconnected
[in]	user_data	The user data to be passed to the rpc_port_proxy_disconnected_event_cb() function

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL

int rpc_port_proxy_add_received_event_cb	(	rpc_port_proxy_h	h,
		rpc_port_proxy_received_event_cb	cb,
		void *	user_data
	)

Adds a proxy received callback.

Since :: 5.0

Parameters:

[in]	h	The rpc port proxy handle
[in]	cb	The callback function to be called when proxy received data
[in]	user_data	The user data to be passed to the rpc_port_proxy_received_event_cb() function

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL

int rpc_port_proxy_add_rejected_event_cb	(	rpc_port_proxy_h	h,
		rpc_port_proxy_rejected_event_cb	cb,
		void *	user_data
	)

Adds a proxy rejected callback.

Since :: 5.0

Parameters:

[in]	h	The rpc port proxy handle
[in]	cb	The callback function to be called when proxy is rejected
[in]	user_data	The user data to be passed to the rpc_port_proxy_rejected_event_cb() function

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL

int rpc_port_proxy_connect	(	rpc_port_proxy_h	h,
		const char *	appid,
		const char *	port
	)

Connects to port of appid.

To send and receive data, the proxy should connect to port of stub

Since :: 5.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/appmanager.launch
http://tizen.org/privilege/datasharing

Remarks:: If you want to use this function, you must add privileges.

Parameters:

[in]	h	The rpc port proxy handle
[in]	appid	The target stub appid
[in]	port	The name of rpc port

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_PERMISSION_DENIED	Permission denied
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL
RPC_PORT_ERROR_IO_ERROR	Internal I/O error

int rpc_port_proxy_connect_sync	(	rpc_port_proxy_h	h,
		const char *	appid,
		const char *	port_name
	)

Connects to port_name of appid synchronously.

To send and receive data, the proxy should connect to port of stub.

Since :: 6.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/appmanager.launch
http://tizen.org/privilege/datasharing

Parameters:

[in]	h	The rpc port proxy handle
[in]	appid	The application ID of the target stub
[in]	port_name	The name of rpc port

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_PERMISSION_DENIED	Permission denied
RPC_PORT_ERROR_INVALID_PARAMETER	Invalid parameter
RPC_PORT_ERROR_IO_ERROR	I/O error

int rpc_port_proxy_create ( rpc_port_proxy_h * h )

Creates a rpc port proxy handle.

Since :: 5.0

Remarks:: You must release h using rpc_port_proxy_destroy().

Parameters:

[out] h The rpc port proxy handle that is newly created

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL

See also:: rpc_port_proxy_destroy()

int rpc_port_proxy_destroy ( rpc_port_proxy_h h )

Destroys a rpc port proxy handle.

Since :: 5.0

Parameters:

[in] h The rpc port proxy handle

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL

See also:: rpc_port_proxy_create()

int rpc_port_proxy_get_port	(	rpc_port_proxy_h	h,
		rpc_port_port_type_e	type,
		rpc_port_h *	port
	)

Gets a port from proxy handle.

Since :: 5.0

Remarks:: This handle port will not be valid if the proxy was disconnected or destroyed.

Parameters:

[in]	h	The rpc port proxy handle
[in]	type	The type of port
[out]	port	The port to communicate

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL
RPC_PORT_ERROR_IO_ERROR	No available ports

See also:: rpc_port_write(); rpc_port_read(); rpc_port_parcel_create_from_port(); rpc_port_parcel_send();

int rpc_port_read	(	rpc_port_h	h,
		void *	buf,
		unsigned int	size
	)

Reads data from an RPC port.

Since :: 5.0

Parameters:

[in]	h	The rpc port handle
[out]	buf	Buffer for reading data
[in]	size	Size for reading data

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL
RPC_PORT_ERROR_IO_ERROR	Internal I/O error

See also:: rpc_port_write()

int rpc_port_set_private_sharing	(	rpc_port_h	port,
		const char *	path
	)

Sets the path of the private sharing file.

See the description of rpc_port_set_private_sharing_array() for details.

Since :: 6.0

Parameters:

[in]	port	The rpc port handle
[in]	path	The path of the file

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	Invalid parameter
RPC_PORT_ERROR_IO_ERROR	I/O error

See also:: rpc_port_set_private_sharing_array(); rpc_port_unset_private_sharing()

int rpc_port_set_private_sharing_array	(	rpc_port_h	port,
		const char *	paths[],
		unsigned int	size
	)

Sets the paths of private sharing files.

If all added paths are under the caller application's data path which can be obtained by calling app_get_data_path() function, those will be shared to the target application. Platform will grant a temporary permission to the target application for those files and revoke it when the target application is terminated or rpc_port_unset_private_sharing() is called. Paths should be regular files. The target application can just read them. Note that the target application doesn't have read permission of the directory that is obtained by caller's app_get_data_path(), You should open the file path with read only mode directly. For example, access() call to the file path will return error because access() needs the read permission of the directory. The target application can call open() with O_RDONLY mode for the passed file path, because platform grants read permission to the passed file path.

Since :: 6.0

Parameters:

[in]	port	The rpc port handle
[in]	paths	The array of paths of files
[in]	size	The size of the array of the paths

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	Invalid parameter
RPC_PORT_ERROR_IO_ERROR	I/O error

See also:: rpc_port_unset_private_sharing()

int rpc_port_stub_add_connected_event_cb	(	rpc_port_stub_h	h,
		rpc_port_stub_connected_event_cb	cb,
		void *	user_data
	)

Adds a stub connected callback.

Since :: 5.0

Parameters:

[in]	h	The rpc stub stub handle
[in]	cb	The callback function to be called when proxy is connected with the stub
[in]	user_data	The user data to be passed to the rpc_port_stub_connected_event_cb() function

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL

int rpc_port_stub_add_disconnected_event_cb	(	rpc_port_stub_h	h,
		rpc_port_stub_disconnected_event_cb	cb,
		void *	user_data
	)

Adds a stub disconnected callback.

Since :: 5.0

Parameters:

[in]	h	The rpc port stub handle
[in]	cb	The callback function to be called when proxy is disconnected with the stub
[in]	user_data	The user data to be passed to the rpc_port_stub_disconnected_event_cb() function

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL

int rpc_port_stub_add_privilege	(	rpc_port_stub_h	h,
		const char *	privilege
	)

Adds a privilege to the stub.

The stub can control access to the port using tizen privilege. It allows connections only if the proxy which have the privileges.

Since :: 5.0

Parameters:

[in]	h	The rpc port stub handle
[in]	privilege	The privilege to access this stub

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL

int rpc_port_stub_add_received_event_cb	(	rpc_port_stub_h	h,
		rpc_port_stub_received_event_cb	cb,
		void *	user_data
	)

Adds a stub received callback.

Since :: 5.0

Parameters:

[in]	h	The rpc port stub handle
[in]	cb	The callback function to be called when stub received data
[in]	user_data	The user data to be passed to the rpc_port_stub_received_event_cb() function

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL

int rpc_port_stub_create	(	rpc_port_stub_h *	h,
		const char *	port_name
	)

Creates a rpc port stub handle.

Since :: 5.0

Remarks:: You must release h using rpc_port_stub_destroy().

Parameters:

[out]	h	The rpc port stub handle that is newly created
[in]	port_name	The name of the port which want to listen

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL

See also:: rpc_port_stub_destroy()

int rpc_port_stub_destroy ( rpc_port_stub_h h )

Destroys a rpc port stub handle.

Since :: 5.0

Parameters:

[in] h The rpc port stub handle

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL

See also:: rpc_port_stub_create()

int rpc_port_stub_get_port	(	rpc_port_stub_h	h,
		rpc_port_port_type_e	type,
		const char *	instance,
		rpc_port_h *	port
	)

Gets a port from stub handle.

Since :: 5.0

Remarks:: This handle port will not be valid if the instance of the stub was disconnected or destroyed.

Parameters:

[in]	h	The rpc port stub handle
[in]	type	The type of port
[in]	instance	The ID of the instance which is connected
[out]	port	The port to communicate

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL
RPC_PORT_ERROR_IO_ERROR	No available ports

See also:: rpc_port_write(); rpc_port_read(); rpc_port_parcel_create_from_port(); rpc_port_parcel_send();

int rpc_port_stub_listen ( rpc_port_stub_h h )

Listens to the requests for connections.

The stub listens requests to connect by port

Since :: 5.0

Parameters:

[in] h The rpc port stub handle

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL
RPC_PORT_ERROR_IO_ERROR	Internal I/O error

int rpc_port_stub_set_trusted	(	rpc_port_stub_h	h,
		const bool	trusted
	)

Sets trusted to the stub.

The stub can control access to the port using tizen certificate. It allows connections only if the proxy is signed with the same certificate.

Since :: 5.0

Parameters:

[in]	h	The rpc port stub handle
[in]	trusted	Whether stub allows only trusted proxy or not

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL

int rpc_port_unset_private_sharing ( rpc_port_h port )

Unsets the private sharing.

Since :: 6.0

Parameters:

[in] port The rpc port handle

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	Invalid parameter
RPC_PORT_ERROR_IO_ERROR	I/O error

See also:: rpc_port_set_private_sharing_array(); rpc_port_set_private_sharing()

int rpc_port_write	(	rpc_port_h	h,
		const void *	buf,
		unsigned int	size
	)

Writes data to an RPC port.

Since :: 5.0

Parameters:

[in]	h	The rpc port handle
[in]	buf	Buffer for writing data
[in]	size	Size for writing data

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

Return values:

RPC_PORT_ERROR_NONE	Successful
RPC_PORT_ERROR_INVALID_PARAMETER	The specified h is NULL
RPC_PORT_ERROR_IO_ERROR	Internal I/O error

See also:: rpc_port_read()

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation