Client API
[libplayerc]

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

Collaboration diagram for Client API:

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 struct _playerc_client_t playerc_client_t
 Client object data.

Functions

playerc_client_tplayerc_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)
 Wait for response from server (blocking).
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.

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.


Typedef Documentation

Client object data.


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 
)

Wait for response from server (blocking).

Parameters:
client Pointer to client object.
device 
index 
sequence 
Returns:
Will return data size for ack, -1 for nack and -2 for failure 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