A.6 Requesting Configuration Changes

For requesting configuration changes to devices, the C client provides the function player_request():

  /*
   * issue some request to the server. requestlen is the length of the 
   * request.  reply, if non-NULL, will be used to hold the reply; replylen
   * is the size of the buffer (player_request() will not overrun your buffer)
   *
   *   Returns:
   *      0 if everything went OK
   *     -1 if something went wrong (you should probably close the connection!)
   */
  int player_request(player_connection_t* conn, 
                     uint16_t device, uint16_t device_index, 
                     const char* payload, size_t payloadlen, 
                     player_msghdr_t* replyhdr, char* reply, size_t replylen);

This function will build the proper message header, including appropriately byte-swapping the header fields. The caller is responsible for byte-swapping the contents of the payload, which will be copied in as the payload of a message that will be sent to the server. After sending the request, player_request() will wait for the matching reply (consuming and discarding all intervening messages) before returning. If the caller wants to examine the reply, then appropriate buffers should be supplied as replyhdr and reply.