Qsonix Integration - Manual (Page 13)

Qsonix Integration Guide
Page | 13
Two-way Commands
Various commands are provided for the purposes of retrieving data from the server or to receive feedback
of current server status. All commands that are requests of the server to return data will conform to a
standard response format. The response will always include a header that can be used to identify what
type of data is being returned to the client. Data returned will use standard delimiters to aide in parsing
the resulting information. A group delimiter (ASCII 29 – shown in this document as the character ) will be
used to denote the end of the header. A row delimiter (ASCII 30 – shown in this document as the character

) will be used to divide distinct rows of results (as in the case of a multi-row response). A field delimiter
(ASCII 31 - shown in this document as the character ) will be used to delimit multiple values in a response
or within a row of a response. In some special cases, a single field in a response can contain multiple
values (such as the OutputIsPlayingThisTrack field returned from the GETFOR_TRACKSFORPLAYLIST
command). The multi-value delimiter (ASCII 3) will be used to divide individual values within a multi-
valued field in the response.
Commands that return a multi-row response also support paging operations. This feature allows the client
to request data in pages of a specified number of rows and the server will manage the current index
location and support next/back functions from the client. This is designed to support clients that are only
able to display a limited number of items on the screen at a time and will provide the user with page up /
page down buttons to navigate the list.
For example, the command “GET PLAYLISTS” can be used to return a list of playlists from the server. The
response for this command will include a header that will include the data type being returned
“PLAYLISTS”, followed by the current page number and then by the total page count. These values will be
separated by the field delimiter and terminated by the group delimiter. For example, the header portion of
this response would be formatted as follows: PLAYLISTS312
Following the header of this response, the actual list of playlists for the specified page would appear as a
list of rows. Each row will contain multiple values (fields) containing the details of the playlist (including
PlaylistID, Playlist Name, Number of Tracks in Playlist, Total Duration of Playlist (in seconds), Total Duration
of Playlists (as a time-formatted string). For example, each row of the data portion of the response would
be formatted as follows: 327Jazz / Blues Mix115310508:37:30
Note that the entire response packet will then be delimited by a carriage return (ASCII 13).
The typical format of these data retrieval commands will be “GET [datatype] [paging command]”.
Currently, only two types of datatypes are supported, PLAYLISTS and NOWPLAYING. The paging
command can be optionally used to retrieve additional pages and supported commands include: NEXT,
PREVIOUS, FIRST, LAST, REFRESH. In addition, the paging command CURRENT can be used in conjunction
with the NOWPLAYING datatype to retrieve the page that includes the current track in the now playing list.
All variations of the supported commands are listed below.
The GET_xxx commands can be used to retrieve a variety of metadata and allows browsing of the full
media library. Each of these commands accept a PageNumber and PageSize parameter. If a
PageNumber is passed that is greater than the maximum number of pages, the last page will be returned.
The PageNumber parameter can also be passed as a single letter, causing the results to return the first
page that contains results starting with that letter. For example, the command “GET_ALBUMS G 30” will
return the first page of 30 albums that has album titles starting with the letter G. Note that the items
starting with G will not necessarily appear as the first item on the page, but the page will contain the start
of the items that begin with the letter G.
Data Types
The data type of each field in responses is noted in the description of the field. Possible values are listed
below:
String(x) – A string value with a maximum length of x
Int32 – a 32-bit integer value (maximum value of 2,147,483,647)