Client API
[libplayerc]

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 void(* playerc_putmsg_fn_t )(void *device, char *header, char *data)
 Typedef for proxy callback function.
typedef void(* playerc_callback_fn_t )(void *data)
 Typedef for proxy callback function.
typedef _playerc_client_t playerc_client_t
 Client object data.

Functions

playerc_client_t * playerc_client_create (playerc_mclient_t *mclient, const char *host, int port)
 Create a client object.
void playerc_client_destroy (playerc_client_t *client)
 Destroy a client object.
void playerc_client_set_transport (playerc_client_t *client, unsigned int transport)
 Set the transport type.
int playerc_client_connect (playerc_client_t *client)
 Connect to the server.
int playerc_client_disconnect (playerc_client_t *client)
 Disconnect from the server.
int playerc_client_datamode (playerc_client_t *client, uint8_t mode)
 Change the server's data delivery mode.
int playerc_client_requestdata (playerc_client_t *client)
 Request a round of data.
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.
int playerc_client_adddevice (playerc_client_t *client, struct _playerc_device_t *device)
 Add a device proxy.
int playerc_client_deldevice (playerc_client_t *client, struct _playerc_device_t *device)
 Remove a device proxy.
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).
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).
int playerc_client_get_devlist (playerc_client_t *client)
 Get the list of available device ids.
int playerc_client_subscribe (playerc_client_t *client, int code, int index, int access, char *drivername, size_t len)
 Subscribe a device.
int playerc_client_unsubscribe (playerc_client_t *client, int code, int index)
 Unsubscribe a device.
int playerc_client_request (playerc_client_t *client, struct _playerc_device_t *device, uint8_t reqtype, void *req_data, void *rep_data, int rep_len)
 Issue a request to the server and await a reply (blocking).
int playerc_client_peek (playerc_client_t *client, int timeout)
 Test to see if there is pending data.
void * playerc_client_read (playerc_client_t *client)
 Read data from the server (blocking).
void playerc_client_set_request_timeout (playerc_client_t *client, uint seconds)
 Set the timeout for client requests.
void playerc_client_set_retry_limit (playerc_client_t *client, int limit)
 Set the connection retry limit.
void playerc_client_set_retry_time (playerc_client_t *client, double time)
 Set the connection retry sleep time.
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.

Function Documentation

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

For internal use only.

int playerc_client_adddevice (  playerc_client_t *  client,
struct _playerc_device_t *  device
) 
 

Add a device proxy.

For internal use only.

int playerc_client_connect (  playerc_client_t *  client  ) 
 

Connect to the server.

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

playerc_client_t* playerc_client_create (  playerc_mclient_t *  mclient,
const char *  host,
int  port
) 
 

Create a client object.

Parameters:
mclient Multiclient object; set this NULL if this is a stand-alone client.
host Player server host name (i.e., name of the machine with the Player server).
port Player 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.

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:
client Pointer to client object.
mode Data 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.

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

For internal use only.

int playerc_client_deldevice (  playerc_client_t *  client,
struct _playerc_device_t *  device
) 
 

Remove a device proxy.

For internal use only.

void playerc_client_destroy (  playerc_client_t *  client  ) 
 

Destroy a client object.

Parameters:
client Pointer to client object.

int playerc_client_disconnect (  playerc_client_t *  client  ) 
 

Disconnect from the server.

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

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:
client Pointer to client object.
Returns:
Returns 0 on success, non-zero otherwise. Use playerc_error_str() to get a descriptive error message.

int playerc_client_peek (  playerc_client_t *  client,
int  timeout
) 
 

Test to see if there is pending data.

Parameters:
client Pointer to client object.
timeout Timeout value (ms). Set timeout to 0 to check for currently queued data.
Returns:
Returns -1 on error, 0 or 1 otherwise.

void* playerc_client_read (  playerc_client_t *  client  ) 
 

Read data from the server (blocking).

Parameters:
client Pointer 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.

int playerc_client_request (  playerc_client_t *  client,
struct _playerc_device_t *  device,
uint8_t  reqtype,
void *  req_data,
void *  rep_data,
int  rep_len
) 
 

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

For internal use only.

Returns:
Returns -1 on error and -2 on NACK.

int playerc_client_requestdata (  playerc_client_t *  client  ) 
 

Request a round of data.

Parameters:
client Pointer 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.

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:
client Pointer to client object.
interf Interface to set replace rule for (-1 for wildcard)
index Index to set replace rule for (-1 for wildcard)
type Type to set replace rule for (-1 for wildcard), i.e. PLAYER_MSGTYPE_DATA
subtype Message subtype to set replace rule for (-1 for wildcard)
replace Should we replace these messages
Returns:
Returns 0 on success, non-zero otherwise. Use playerc_error_str() to get a descriptive error message.

void playerc_client_set_request_timeout (  playerc_client_t *  client,
uint  seconds
) 
 

Set the timeout for client requests.

Parameters:
client Pointer to client object.
seconds Seconds to wait for a reply.

void playerc_client_set_retry_limit (  playerc_client_t *  client,
int  limit
) 
 

Set the connection retry limit.

Parameters:
client Pointer to the client object
limit The number of times to attempt to reconnect to the server. Give -1 for infinite retry.

void playerc_client_set_retry_time (  playerc_client_t *  client,
double  time
) 
 

Set the connection retry sleep time.

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

void playerc_client_set_transport (  playerc_client_t *  client,
unsigned int  transport
) 
 

Set the transport type.

Parameters:
transport Either PLAYERC_TRANSPORT_UDP or PLAYERC_TRANSPORT_TCP

int playerc_client_subscribe (  playerc_client_t *  client,
int  code,
int  index,
int  access,
char *  drivername,
size_t  len
) 
 

Subscribe a device.

For internal use only.

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

Unsubscribe a device.

For internal use only.

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.

For internal use only.
Last updated 12 September 2005 21:38:45