2.1 PlayerClient

One PlayerClient object is used to control each connection to a Player server. Contained within this object are methods for changing the connection parameters and obtaining access to devices, which we explain next.

Attributes

bool fresh;

Flag set if data has just been read into this client. If you use it, you must set it to false yourself after examining the data.

char hostname[256];

The host of the Player server to which we are connected.

int port;

The port of the Player server to which we are connected.

struct timeval timestamp;

The latest time received from the server.

Methods

PlayerClient(const char* hostname=NULL,
const int port=PLAYER_PORTNUM,
const int protocol=PLAYER_TRANSPORT_TCP)

Make a client and connect it as indicated. If hostname is omitted (or NULL) then the client will not be connected. In that cast, call Connect() yourself later.

PlayerClient(const struct in_addr* hostaddr,
const int port,
const int protocol=PLAYER_TRANSPORT_TCP)

Make a client and connect it as indicated, using a binary IP instead of a hostname

int Connect(const char* hostname="localhost", int port=PLAYER_PORTNUM)

Connect to the indicated host and port.
Returns 0 on success; -1 on error.

int Connect(const struct in_addr* addr, int port)

Connect to the indicated host and port, using a binary IP.
Returns 0 on success; -1 on error.

int ConnectRNS(const char* robotname, const char* hostname="localhost",
int port=PLAYER_PORTNUM)

Connect to a robot, based on its name, by using the Player robot name service (RNS) on the indicated host and port. Returns 0 on success; -1 on error.

int Disconnect()

Disconnect from server.
Returns 0 on success; -1 on error.

bool Connected()

Check if we are connected.

int Read()

This method will read one round of data; that is, it will read until a SYNC packet is received from the server. Depending on which data delivery mode is in use, new data may or may not be received for each open device. The data that is received for each device device will be processed by the appropriate device proxy and stored there for access by your program. If no errors occurred 0 is returned. Otherwise, -1 is returned and diagnostic information is printed to stderr (you should probably close the connection!).

int Write(player_device_id_t device_id,
const char* command, size_t commandlen)

Write a command to the server. This method is not intended for direct use. Rather, device proxies should implement higher-level methods atop this one. Returns 0 on success, -1 otherwise.

int Request(player_device_id_t device_id,
const char* payload,
size_t payloadlen,
player_msghdr_t* replyhdr,
char* reply, size_t replylen)

Send a request to the server. This method is not intended for direct use. Rather, device proxies should implement higher-level methods atop this one. Returns 0 on success, -1 otherwise.

int Request(player_device_id_t device_id,
const char* payload,
size_t payloadlen)

Another form of Request(), this one can be used if the caller is not interested in the reply. This method is not intended for direct use. Rather, device proxies should implement higher-level methods atop this one. Returns 0 if an ACK is received, -1 otherwise.

int RequestDeviceAccess(player_device_id_t device_id,
unsigned char req_access,
unsigned char* grant_access,
char* driver_name = NULL,
int driver_name_len = 0)

Request access to a device; meant mostly for use by client-side device proxy constructors. req_access is requested access. grant_access, if non-NULL, will be filled with the granted access. Returns 0 if everything went OK or -1 if something went wrong.

int SetFrequency(unsigned short freq)

You can change the rate at which your client receives data from the server with this method. The value of freq is interpreted as Hz; this will be the new rate at which your client receives data (when in continuous mode). On error, -1 is returned; otherwise 0.

int SetDataMode(unsigned char mode)

You can toggle the mode in which the server sends data to your client with this method. The mode should be one of:

• PLAYER_DATAMODE_PUSH_ALL (all data at fixed frequency)
• PLAYER_DATAMODE_PULL_ALL (all data on demand)
• PLAYER_DATAMODE_PUSH_NEW (only new new data at fixed freq)
• PLAYER_DATAMODE_PULL_NEW (only new data on demand)

On error, -1 is returned; otherwise 0.

int RequestData()

When in a PULL data delivery mode, you can request a single round of data using this method. On error -1 is returned; otherwise 0.

int Authenticate(char* key)

Attempt to authenticate your client using the provided key. If authentication fails, the server will close your connection.

int LookupPort(const char* name)

Documentation on LookupPort goes here