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

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

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

typedef struct _playerc_client_t playerc_client_t

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:

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

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.

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:

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.

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:

client Pointer to client object.

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

PLAYERC_EXPORT int playerc_client_disconnect_retry ( playerc_client_t * client )

Disconnect from the server, with potential retry.

Parameters:

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

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

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.

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

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:

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.

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:

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.

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:

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.

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

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

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

PLAYERC_EXPORT 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

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.

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

Function Documentation