Client API
[libplayerc]
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 void(* playerc_callback_fn_t)(void *data) |
Typedef for proxy callback function
typedef struct _playerc_client_t playerc_client_t |
Client object data.
typedef void(* playerc_putmsg_fn_t)(void *device, char *header, char *data) |
Typedef for proxy callback function
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_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_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.
- 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, | |||
void * | req_data, | |||
void * | rep_data, | |||
int | rep_len | |||
) |
Issue a request to the server and await a reply (blocking).
For internal use only.
- 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.
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 serverIf 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, | |
uint | seconds | |||
) |
Set the timeout for client requests.
- Parameters:
-
client Pointer to client object. seconds Seconds to wait for a reply.
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.
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.
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.