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

Functions
PLAYERC_EXPORT playerc_client_t *	playerc_client_create (playerc_mclient_t mclient, const char host, int port)
	Create a client object. More...

PLAYERC_EXPORT void	playerc_client_destroy (playerc_client_t *client)
	Destroy a client object. More...

PLAYERC_EXPORT void	playerc_client_set_transport (playerc_client_t *client, unsigned int transport)
	Set the transport type. More...

PLAYERC_EXPORT int	playerc_client_connect (playerc_client_t *client)
	Connect to the server. More...

PLAYERC_EXPORT int	playerc_client_disconnect (playerc_client_t *client)
	Disconnect from the server. More...

PLAYERC_EXPORT int	playerc_client_disconnect_retry (playerc_client_t *client)
	Disconnect from the server, with potential retry. More...

PLAYERC_EXPORT int	playerc_client_datamode (playerc_client_t *client, uint8_t mode)
	Change the server's data delivery mode. More...

PLAYERC_EXPORT int	playerc_client_requestdata (playerc_client_t *client)
	Request a round of data. More...

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

PLAYERC_EXPORT int	playerc_client_adddevice (playerc_client_t client, struct _playerc_device_t device)
	Add a device proxy. More...

PLAYERC_EXPORT int	playerc_client_deldevice (playerc_client_t client, struct _playerc_device_t device)
	Remove a device proxy. More...

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

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

PLAYERC_EXPORT int	playerc_client_get_devlist (playerc_client_t *client)
	Get the list of available device ids. More...

PLAYERC_EXPORT int	playerc_client_subscribe (playerc_client_t client, int code, int index, int access, char drivername, size_t len)
	Subscribe a device. More...

PLAYERC_EXPORT int	playerc_client_unsubscribe (playerc_client_t *client, int code, int index)
	Unsubscribe a device. More...

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

PLAYERC_EXPORT int	playerc_client_peek (playerc_client_t *client, int timeout)
	Test to see if there is pending data. More...

PLAYERC_EXPORT int	playerc_client_internal_peek (playerc_client_t *client, int timeout)
	Test to see if there is pending data. More...

PLAYERC_EXPORT void *	playerc_client_read (playerc_client_t *client)
	Read data from the server (blocking). More...

PLAYERC_EXPORT int	playerc_client_read_nonblock (playerc_client_t *client)
	Read and process a packet (nonblocking) More...

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

PLAYERC_EXPORT void	playerc_client_set_request_timeout (playerc_client_t *client, uint32_t seconds)
	Set the timeout for client requests. More...

PLAYERC_EXPORT void	playerc_client_set_retry_limit (playerc_client_t *client, int limit)
	Set the connection retry limit. More...

PLAYERC_EXPORT void	playerc_client_set_retry_time (playerc_client_t *client, double time)
	Set the connection retry sleep time. More...

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

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

◆ playerc_client_t

typedef struct _playerc_client_t playerc_client_t

Client object data.

Function Documentation

◆ playerc_client_addcallback()

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_client_adddevice()

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

Add a device proxy.

◆ playerc_client_connect()

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_client_create()

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_client_datamode()

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_client_delcallback()

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_client_deldevice()

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

Remove a device proxy.

◆ playerc_client_destroy()

PLAYERC_EXPORT void playerc_client_destroy ( playerc_client_t * client )

Destroy a client object.

Parameters

client Pointer to client object.

◆ playerc_client_disconnect()

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_client_disconnect_retry()

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_client_get_devlist()

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_client_internal_peek()

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_client_peek()

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

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_client_read()

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_client_read_nonblock()

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_client_read_nonblock_withproxy()

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_client_request()

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_client_requestdata()

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_client_set_replace_rule()

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_client_set_request_timeout()

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_client_set_retry_limit()

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_client_set_retry_time()

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_client_set_transport()

PLAYERC_EXPORT void playerc_client_set_transport	(	playerc_client_t *	client,
		unsigned int	transport
	)

Set the transport type.

Parameters

client	Pointer to client object.
transport	Either PLAYERC_TRANSPORT_UDP or PLAYERC_TRANSPORT_TCP

◆ playerc_client_subscribe()

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_client_unsubscribe()

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

Unsubscribe a device.

◆ playerc_client_write()

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.

Detailed Description

Classes

Typedefs

Functions

Variables

Typedef Documentation

◆ playerc_client_t

Function Documentation

◆ playerc_client_addcallback()

◆ playerc_client_adddevice()

◆ playerc_client_connect()

◆ playerc_client_create()

◆ playerc_client_datamode()

◆ playerc_client_delcallback()

◆ playerc_client_deldevice()

◆ playerc_client_destroy()

◆ playerc_client_disconnect()

◆ playerc_client_disconnect_retry()

◆ playerc_client_get_devlist()

◆ playerc_client_internal_peek()

◆ playerc_client_peek()

◆ playerc_client_read()

◆ playerc_client_read_nonblock()

◆ playerc_client_read_nonblock_withproxy()

◆ playerc_client_request()

◆ playerc_client_requestdata()

◆ playerc_client_set_replace_rule()

◆ playerc_client_set_request_timeout()

◆ playerc_client_set_retry_limit()

◆ playerc_client_set_retry_time()

◆ playerc_client_set_transport()

◆ playerc_client_subscribe()

◆ playerc_client_unsubscribe()

◆ playerc_client_write()