Tizen Native API  5.0
RPC Port

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 :
4.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 :
4.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 :
4.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 :
4.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 :
4.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 :
4.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 :
4.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 :
4.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 :
4.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 :
4.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 :
4.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 :
4.0
Enumerator:
RPC_PORT_PORT_MAIN 

Main channel

RPC_PORT_PORT_CALLBACK 

The channel for callbacks


Function Documentation

Adds a proxy connected callback.

Since :
4.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 :
4.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 :
4.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 :
4.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 :
4.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_INVALID_PARAMETERThe specified h is NULL
RPC_PORT_ERROR_IO_ERRORInternal I/O error
RPC_PORT_ERROR_PERMISSION_DENIEDPermission denied

Creates a rpc port proxy handle.

Since :
4.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 :
4.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 :
4.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 :
4.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()

Adds a stub connected callback.

Since :
4.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 :
4.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 :
4.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 :
4.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 :
4.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 :
4.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 :
4.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 :
4.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 :
4.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
int rpc_port_write ( rpc_port_h  h,
const void *  buf,
unsigned int  size 
)

Writes data to an RPC port.

Since :
4.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()