A.4 Reading Data

For obtaining data from devices, the C client provides the rather simple function player_read():

  /*
   * read from the indicated connection.  put the data in buffer, up to
   * bufferlen.
   *
   * Returns:
   *    0 if everything went OK
   *   -1 if something went wrong (you should probably close the connection!)
   */
  int player_read(player_connection_t* conn, player_msghdr_t* hdr,
                  char* payload, size_t payloadlen);

This function will read one data packet from the server, blocking if no packet is available. It is the caller's responsibility to provide sufficient storage for the header and payload, and player_read() will not overrun the provided buffers. After calling player_read(), the user will presumably examine the fields of the header in order to know how to process the payload. Note that player_read() will appropriately byte-swap all fields in the header, but will not transform the contents of the payload in any way. A simple example:

  ...
  player_msghdr_t hdr;
  char data[PLAYER_MAX_MESSAGE_SIZE];

  if(player_read(&conn, &hdr, data, sizeof(data)) == -1)
    exit(1);
  ...