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

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

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

Last updated 12 September 2005 21:38:45