Client API

The client object manages the connection with the Player server; it is responsible for reading new data, setting data transmission modes and so on. More...


Detailed Description

The client object manages the connection with the Player server; it is responsible for reading new data, setting data transmission modes and so on.

The client object must be created and connected before device proxies are initialized.

Classes

struct  playerc_device_info_t
 Info about an available (but not necessarily subscribed) device. More...
struct  _playerc_client_t
 Client object data. More...

Typedefs

typedef struct _playerc_client_t playerc_client_t
 Client object data.

Functions

PLAYERC_EXPORT playerc_client_tplayerc_client_create (playerc_mclient_t *mclient, const char *host, int port)
 Create a client object.
PLAYERC_EXPORT void playerc_client_destroy (playerc_client_t *client)
 Destroy a client object.
PLAYERC_EXPORT void playerc_client_set_transport (playerc_client_t *client, unsigned int transport)
 Set the transport type.
PLAYERC_EXPORT int playerc_client_connect (playerc_client_t *client)
 Connect to the server.
PLAYERC_EXPORT int playerc_client_disconnect (playerc_client_t *client)
 Disconnect from the server.
PLAYERC_EXPORT int playerc_client_disconnect_retry (playerc_client_t *client)
 Disconnect from the server, with potential retry.
PLAYERC_EXPORT int playerc_client_datamode (playerc_client_t *client, uint8_t mode)
 Change the server's data delivery mode.
PLAYERC_EXPORT int playerc_client_requestdata (playerc_client_t *client)
 Request a round of data.
PLAYERC_EXPORT int playerc_client_set_replace_rule (playerc_client_t *client, int interf, int index, int type, int subtype, int replace)
 Set a replace rule for the client queue on the server.
PLAYERC_EXPORT int playerc_client_adddevice (playerc_client_t *client, struct _playerc_device_t *device)
 Add a device proxy.
PLAYERC_EXPORT int playerc_client_deldevice (playerc_client_t *client, struct _playerc_device_t *device)
 Remove a device proxy.
PLAYERC_EXPORT int playerc_client_addcallback (playerc_client_t *client, struct _playerc_device_t *device, playerc_callback_fn_t callback, void *data)
 Add user callbacks (called when new data arrives).
PLAYERC_EXPORT int playerc_client_delcallback (playerc_client_t *client, struct _playerc_device_t *device, playerc_callback_fn_t callback, void *data)
 Remove user callbacks (called when new data arrives).
PLAYERC_EXPORT int playerc_client_get_devlist (playerc_client_t *client)
 Get the list of available device ids.
PLAYERC_EXPORT int playerc_client_subscribe (playerc_client_t *client, int code, int index, int access, char *drivername, size_t len)
 Subscribe a device.
PLAYERC_EXPORT int playerc_client_unsubscribe (playerc_client_t *client, int code, int index)
 Unsubscribe a device.
PLAYERC_EXPORT int playerc_client_request (playerc_client_t *client, struct _playerc_device_t *device, uint8_t reqtype, const void *req_data, void **rep_data)
 Issue a request to the server and await a reply (blocking).
PLAYERC_EXPORT int playerc_client_peek (playerc_client_t *client, int timeout)
 Test to see if there is pending data.
PLAYERC_EXPORT int playerc_client_internal_peek (playerc_client_t *client, int timeout)
 Test to see if there is pending data.
PLAYERC_EXPORT void * playerc_client_read (playerc_client_t *client)
 Read data from the server (blocking).
PLAYERC_EXPORT int playerc_client_read_nonblock (playerc_client_t *client)
 Read and process a packet (nonblocking)
PLAYERC_EXPORT int playerc_client_read_nonblock_withproxy (playerc_client_t *client, void **proxy)
 Read and process a packet (nonblocking), fills in pointer to proxy that got data.
PLAYERC_EXPORT void playerc_client_set_request_timeout (playerc_client_t *client, uint32_t seconds)
 Set the timeout for client requests.
PLAYERC_EXPORT void playerc_client_set_retry_limit (playerc_client_t *client, int limit)
 Set the connection retry limit.
PLAYERC_EXPORT void playerc_client_set_retry_time (playerc_client_t *client, double time)
 Set the connection retry sleep time.
PLAYERC_EXPORT int playerc_client_write (playerc_client_t *client, struct _playerc_device_t *device, uint8_t subtype, void *cmd, double *timestamp)
 Write data to the server.

Variables

PLAYERC_EXPORT typedef void(* playerc_putmsg_fn_t )(void *device, char *header, char *data)
 Typedef for proxy callback function.
PLAYERC_EXPORT typedef void(* playerc_callback_fn_t )(void *data)
 Typedef for proxy callback function.

Typedef Documentation

Client object data.


Function Documentation

PLAYERC_EXPORT int playerc_client_addcallback ( playerc_client_t client,
struct _playerc_device_t device,
playerc_callback_fn_t  callback,
void *  data 
)

Add user callbacks (called when new data arrives).

PLAYERC_EXPORT int playerc_client_adddevice ( playerc_client_t client,
struct _playerc_device_t device 
)

Add a device proxy.

PLAYERC_EXPORT int playerc_client_connect ( playerc_client_t client)

Connect to the server.

Parameters:
clientPointer to client object.
Returns:
Returns 0 on success, non-zero otherwise. Use playerc_error_str() to get a descriptive error message.
PLAYERC_EXPORT playerc_client_t* playerc_client_create ( playerc_mclient_t mclient,
const char *  host,
int  port 
)

Create a client object.

Parameters:
mclientMulticlient object; set this NULL if this is a stand-alone client.
hostPlayer server host name (i.e., name of the machine with the Player server).
portPlayer server port (typically 6665, but depends on the server configuration).
Returns:
Returns a newly allocated pointer to the client object; use playerc_client_destroy() to delete the object.
PLAYERC_EXPORT int playerc_client_datamode ( playerc_client_t client,
uint8_t  mode 
)

Change the server's data delivery mode.

Be sure to read about data modes before using this function.

Parameters:
clientPointer to client object.
modeData delivery mode; must be one of PLAYERC_DATAMODE_PUSH, PLAYERC_DATAMODE_PULL; the defalt mode is PLAYERC_DATAMODE_PUSH.
Returns:
Returns 0 on success, non-zero otherwise. Use playerc_error_str() to get a descriptive error message.
PLAYERC_EXPORT int playerc_client_delcallback ( playerc_client_t client,
struct _playerc_device_t device,
playerc_callback_fn_t  callback,
void *  data 
)

Remove user callbacks (called when new data arrives).

PLAYERC_EXPORT int playerc_client_deldevice ( playerc_client_t client,
struct _playerc_device_t device 
)

Remove a device proxy.

PLAYERC_EXPORT void playerc_client_destroy ( playerc_client_t client)

Destroy a client object.

Parameters:
clientPointer to client object.
PLAYERC_EXPORT int playerc_client_disconnect ( playerc_client_t client)

Disconnect from the server.

Parameters:
clientPointer to client object.
Returns:
Returns 0 on success, non-zero otherwise. Use playerc_error_str() to get a descriptive error message.
PLAYERC_EXPORT int playerc_client_disconnect_retry ( playerc_client_t client)

Disconnect from the server, with potential retry.

Parameters:
clientPointer to client object.
Returns:
Returns 0 on success, non-zero otherwise.
PLAYERC_EXPORT int playerc_client_get_devlist ( playerc_client_t client)

Get the list of available device ids.

This function queries the server for the list of available devices, and write result to the devinfos list in the client object.

Parameters:
clientPointer to client object.
Returns:
Returns 0 on success, non-zero otherwise. Use playerc_error_str() to get a descriptive error message.
PLAYERC_EXPORT int playerc_client_internal_peek ( playerc_client_t client,
int  timeout 
)

Test to see if there is pending data.

Don't send a request for data. This function is reliant on a call being made elsewhere to request data from the server.

Parameters:
clientPointer to client object.
timeoutTimeout value (ms). Set timeout to 0 to check for currently queued data.
Returns:
Returns -1 on error, 0 or 1 otherwise.
PLAYERC_EXPORT int playerc_client_peek ( playerc_client_t client,
int  timeout 
)

Test to see if there is pending data.

Send a data request if one has not been sent already. A data request is necessary to provoke a response from the server.

Parameters:
clientPointer to client object.
timeoutTimeout value (ms). Set timeout to 0 to check for currently queued data.
Returns:
Returns -1 on error, 0 or 1 otherwise.
PLAYERC_EXPORT void* playerc_client_read ( playerc_client_t client)

Read data from the server (blocking).

In PUSH mode this will read and process a single message. In PULL mode this will process a full batch of messages up to the sync from the server.

Parameters:
clientPointer to client object.
Returns:
PUSH mode: For data packets, will return the ID of the proxy that got the data; for synch packets, will return the ID of the client itself; on error, will return NULL. PULL mode: Will return NULL on error, the ID of the client on success. Will never return the ID of a proxy other than the client.
PLAYERC_EXPORT int playerc_client_read_nonblock ( playerc_client_t client)

Read and process a packet (nonblocking)

Returns:
0 if no data recieved, 1 if data recieved and -1 on error
PLAYERC_EXPORT int playerc_client_read_nonblock_withproxy ( playerc_client_t client,
void **  proxy 
)

Read and process a packet (nonblocking), fills in pointer to proxy that got data.

Returns:
0 if no data recieved, 1 if data recieved and -1 on error
PLAYERC_EXPORT int playerc_client_request ( playerc_client_t client,
struct _playerc_device_t device,
uint8_t  reqtype,
const void *  req_data,
void **  rep_data 
)

Issue a request to the server and await a reply (blocking).

The rep_data pointer is filled with a pointer to the response data received. It is the callers responisbility to free this memory with the approriate player _free method.

If an error is returned then no data will have been stored in rep_data.

Returns:
Returns -1 on error and -2 on NACK.
PLAYERC_EXPORT int playerc_client_requestdata ( playerc_client_t client)

Request a round of data.

Parameters:
clientPointer to client object.

Request a round of data; only valid when in a request/reply (aka PULL) data delivery mode. But you don't need to call this function, because playerc_client_read will do it for you if the client is in a PULL mode.

Use playerc_client_datamode to change modes.

PLAYERC_EXPORT int playerc_client_set_replace_rule ( playerc_client_t client,
int  interf,
int  index,
int  type,
int  subtype,
int  replace 
)

Set a replace rule for the client queue on the server.

If a rule with the same pattern already exists, it will be replaced with the new rule (i.e., its setting to replace will be updated).

Parameters:
clientPointer to client object.
interfInterface to set replace rule for (-1 for wildcard)
indexIndex to set replace rule for (-1 for wildcard)
typeType to set replace rule for (-1 for wildcard), i.e. PLAYER_MSGTYPE_DATA
subtypeMessage subtype to set replace rule for (-1 for wildcard)
replaceShould we replace these messages
Returns:
Returns 0 on success, non-zero otherwise. Use playerc_error_str() to get a descriptive error message.
PLAYERC_EXPORT void playerc_client_set_request_timeout ( playerc_client_t client,
uint32_t  seconds 
)

Set the timeout for client requests.

Parameters:
clientPointer to client object.
secondsSeconds to wait for a reply.

Referenced by PlayerCc::PlayerClient::SetRequestTimeout().

PLAYERC_EXPORT void playerc_client_set_retry_limit ( playerc_client_t client,
int  limit 
)

Set the connection retry limit.

Parameters:
clientPointer to the client object
limitThe number of times to attempt to reconnect to the server. Give -1 for infinite retry.

Referenced by PlayerCc::PlayerClient::SetRetryLimit().

PLAYERC_EXPORT void playerc_client_set_retry_time ( playerc_client_t client,
double  time 
)

Set the connection retry sleep time.

Parameters:
clientPointer to the client object
timeThe amount of time, in seconds, to sleep between reconnection attempts.

Referenced by PlayerCc::PlayerClient::SetRetryTime().

PLAYERC_EXPORT void playerc_client_set_transport ( playerc_client_t client,
unsigned int  transport 
)

Set the transport type.

Parameters:
clientPointer to client object.
transportEither PLAYERC_TRANSPORT_UDP or PLAYERC_TRANSPORT_TCP
PLAYERC_EXPORT int playerc_client_subscribe ( playerc_client_t client,
int  code,
int  index,
int  access,
char *  drivername,
size_t  len 
)

Subscribe a device.

PLAYERC_EXPORT int playerc_client_unsubscribe ( playerc_client_t client,
int  code,
int  index 
)

Unsubscribe a device.

PLAYERC_EXPORT int playerc_client_write ( playerc_client_t client,
struct _playerc_device_t device,
uint8_t  subtype,
void *  cmd,
double *  timestamp 
)

Write data to the server.