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