Tizen Native API  6.0

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.

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]receiverThe target stub app id
[in]port_nameThe name of the port
[in]portThe rpc port handle for reading and writing
[in]user_dataThe 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]receiverThe target stub app id
[in]port_nameThe name of the port
[in]user_dataThe 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]receiverThe target stub app id
[in]port_nameThe name of the port
[in]user_dataThe 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]receiverThe target stub app id
[in]port_nameThe name of the port
[in]user_dataThe 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]senderThe target proxy app id
[in]instanceThe information of the request
[in]user_dataThe 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]senderThe target proxy app id
[in]instanceThe information of the request
[in]user_dataThe 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]senderThe target proxy app id
[in]instanceThe information of the request
[in]portThe rpc port handle for reading and writing
[in]user_dataThe 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

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

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

Adds a proxy connected callback.

Since :
5.0
Parameters:
[in]hThe rpc port proxy handle
[in]cbThe callback function to be called when proxy is connected
[in]user_dataThe 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_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL

Adds a proxy disconnected callback.

Since :
5.0
Parameters:
[in]hThe rpc port proxy handle
[in]cbThe callback function to be called when proxy is disconnected
[in]user_dataThe 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_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL

Adds a proxy received callback.

Since :
5.0
Parameters:
[in]hThe rpc port proxy handle
[in]cbThe callback function to be called when proxy received data
[in]user_dataThe 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_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL

Adds a proxy rejected callback.

Since :
5.0
Parameters:
[in]hThe rpc port proxy handle
[in]cbThe callback function to be called when proxy is rejected
[in]user_dataThe 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_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe 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]hThe rpc port proxy handle
[in]appidThe target stub appid
[in]portThe name of rpc port
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_PERMISSION_DENIEDPermission denied
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL
RPC_PORT_ERROR_IO_ERRORInternal 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]hThe rpc port proxy handle
[in]appidThe application ID of the target stub
[in]port_nameThe name of rpc port
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_PERMISSION_DENIEDPermission denied
RPC_PORT_ERROR_INVALID_PARAMETERInvalid parameter
RPC_PORT_ERROR_IO_ERRORI/O error

Creates a rpc port proxy handle.

Since :
5.0
Remarks:
You must release h using rpc_port_proxy_destroy().
Parameters:
[out]hThe rpc port proxy handle that is newly created
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL
See also:
rpc_port_proxy_destroy()

Destroys a rpc port proxy handle.

Since :
5.0
Parameters:
[in]hThe rpc port proxy handle
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL
See also:
rpc_port_proxy_create()

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]hThe rpc port proxy handle
[in]typeThe type of port
[out]portThe port to communicate
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL
RPC_PORT_ERROR_IO_ERRORNo 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]hThe rpc port handle
[out]bufBuffer for reading data
[in]sizeSize for reading data
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL
RPC_PORT_ERROR_IO_ERRORInternal 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]portThe rpc port handle
[in]pathThe path of the file
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERInvalid parameter
RPC_PORT_ERROR_IO_ERRORI/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]portThe rpc port handle
[in]pathsThe array of paths of files
[in]sizeThe size of the array of the paths
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERInvalid parameter
RPC_PORT_ERROR_IO_ERRORI/O error
See also:
rpc_port_unset_private_sharing()

Adds a stub connected callback.

Since :
5.0
Parameters:
[in]hThe rpc stub stub handle
[in]cbThe callback function to be called when proxy is connected with the stub
[in]user_dataThe 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_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL

Adds a stub disconnected callback.

Since :
5.0
Parameters:
[in]hThe rpc port stub handle
[in]cbThe callback function to be called when proxy is disconnected with the stub
[in]user_dataThe 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_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe 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]hThe rpc port stub handle
[in]privilegeThe privilege to access this stub
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL

Adds a stub received callback.

Since :
5.0
Parameters:
[in]hThe rpc port stub handle
[in]cbThe callback function to be called when stub received data
[in]user_dataThe 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_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe 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]hThe rpc port stub handle that is newly created
[in]port_nameThe name of the port which want to listen
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL
See also:
rpc_port_stub_destroy()

Destroys a rpc port stub handle.

Since :
5.0
Parameters:
[in]hThe rpc port stub handle
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe 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]hThe rpc port stub handle
[in]typeThe type of port
[in]instanceThe ID of the instance which is connected
[out]portThe port to communicate
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL
RPC_PORT_ERROR_IO_ERRORNo available ports
See also:
rpc_port_write()
rpc_port_read()
rpc_port_parcel_create_from_port()
rpc_port_parcel_send();

Listens to the requests for connections.

The stub listens requests to connect by port

Since :
5.0
Parameters:
[in]hThe rpc port stub handle
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL
RPC_PORT_ERROR_IO_ERRORInternal 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]hThe rpc port stub handle
[in]trustedWhether stub allows only trusted proxy or not
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL

Unsets the private sharing.

Since :
6.0
Parameters:
[in]portThe rpc port handle
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERInvalid parameter
RPC_PORT_ERROR_IO_ERRORI/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]hThe rpc port handle
[in]bufBuffer for writing data
[in]sizeSize for writing data
Returns:
0 on success, otherwise a negative error value
Return values:
RPC_PORT_ERROR_NONESuccessful
RPC_PORT_ERROR_INVALID_PARAMETERThe specified h is NULL
RPC_PORT_ERROR_IO_ERRORInternal I/O error
See also:
rpc_port_read()