Client API
[libplayerc]

Collaboration diagram for Client API:

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_disconnect_retry (playerc_client_t *client)
 Disconnect from the server, with potential retry.
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, const void *req_data, void **rep_data)
 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.
int playerc_client_internal_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).
int playerc_client_read_nonblock (playerc_client_t *client)
int playerc_client_read_nonblock_withproxy (playerc_client_t *client, void **proxy)
void playerc_client_set_request_timeout (playerc_client_t *client, uint32_t 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_disconnect_retry ( playerc_client_t *  client  ) 

Disconnect from the server, with potential retry.

For internal use only.

Parameters:
client Pointer to client object.
Returns:
Returns 0 on success, non-zero otherwise.

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

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:
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,
const void *  req_data,
void **  rep_data 
)

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

For internal use only.

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.

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,
uint32_t  seconds 
)

Set the timeout for client requests.

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

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

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.

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

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.

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

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