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.
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_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_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_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_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