ImageServer - audio speaker requests and responses
Speaker device commands supported by the ImageServer protocol.
ImageServer protocol
All commands are sent using the HTTP/1.1 protocol.
The following HTTP/1.1 response codes can be returned on this interface:
Response code |
Description |
|---|---|
200 OK |
Request was processed successfully |
400 Bad Request |
Invalid or malformatted request |
403 Forbidden |
Access to the API is denied |
500 Internal Server Error |
An exception occurred while processing the request |
503 Service Unavailable |
The request cannot be processed at the moment; the client is advised to retry after the time interval specified in the “Retry-After” HTTP header |
An invalid or malformatted request gets a 400 Bad Request response:
HTTP/1.1 400 Bad Request
Content-Length: 0
X-MethodName: connect
X-RequestId: [number]
␍␊ (<-- HTTP standard CR-LF)
<?xml version="1.0" encoding="UTF-8"?>
<methodresponse>
<errorNumber>[a-5-digit-number]</errorNumber>
<subErrorNumber>[a-1-digit-number]</subErrorNumber>
</methodresponse>The errors can be:
Error number |
Sub-error number |
Description |
|---|---|---|
20001 |
any |
There is a problem with the specified security token. |
20001 |
1 |
Occurs when no token was specified by the client. |
20001 |
2 |
Occurs when the validation of the supplied token failed. |
20001 |
3 |
Occurs when the supplied token had expired. |
20001 |
4 |
Occurs when the supplied token could not be validated at the moment of the request; the client should retry later. |
connect
The connect request checks the token, and subsequently allows the client to send commands to it. Under normal circumstances, this request would complete in a timely fashion. The client must obtain a valid token through the SOAP login request prior to this connect request.
Client request
POST /imageserver?methodcall=connect HTTP/1.1
Content-Type: text/xml
Content-Length: [number]
X-RequestId: [number]
␍␊
<?xml version="1.0" encoding="UTF-8"?>
<methodcall>
<token>[text]</token>
</methodcall>Server response (success)
HTTP/1.1 200 OK
Content-Length: 0
X-MethodName: connect
X-RequestId: [number]
␍␊ (<-- HTTP standard CR-LF)Server response (error – token invalid)
HTTP/1.1 401 Unauthorized
Content-Length: 0
X-MethodName: connect
X-RequestId: [number]
␍␊ (<-- HTTP standard CR-LF)initialize
Called by the client if the connect request was successful to initialize the requested devices. Setting the value of the action node to speak initializes the speaker device for an incoming audio stream from the client. This request might start a lengthy operation on the server which could lead to a delayed response.
Client request
POST /imageserver?methodcall=initialize HTTP/1.1
Content-Type: text/xml
Content-Length: [number]
X-RequestId: [number]
␍␊
<?xml version="1.0" encoding="utf-8"?>
<methodcall>
<action>speak</action>
<devices>
<device>
<id>[text(guid)]</id>
</device>
</devices>
</methodcall>Server response (success)
HTTP/1.1 200 OK
Content-Length: 0
X-MethodName: initialize
X-RequestId: [number]
␍␊ (<-- HTTP standard CR-LF)Server response (error)
HTTP/1.1 409 Conflict
Content-Type: text/xml
Content-Length: [number]
X-MethodName: connect
X-RequestId: [number]
␍␊
<?xml version="1.0" encoding="utf-8"?>
<methodresponse>
<devices>
<device>
<id>[text(guid)]</id>
<success>yes/no</success>
<errorreason>[text]</errorreason> Optional
</device>
</devices>
</methodresponse>beginspeak
This request is sent by the client before transmitting audio data to inform the server which speaker devices the following audio stream should be sent to. An endspeak request is expected to follow the audio data stream. The requests beginspeak and endspeak would usually be sent by the client when the user presses the microphone speak button and releases the microphone speak button, respectively. The conversation will not be interrupted by other connected clients if the exclusive flag is set for the speak device *. The supplied device list must contain all, or a subset of, the devices used in the connect request.
* To allow more than one client to speak on the same speak device, a merge of the audio streams is required before they are sent to the device. Until this feature is implemented, the exclusive flag must be set to yes.
Client request
POST /imageserver?methodcall=beginspeak HTTP/1.1
Content-Type: text/xml
Content-Length: [number]
X-RequestId: [number]
␍␊
<?xml version="1.0" encoding="utf-8"?>
<methodcall>
<action>speak</action>
<devices>
<device>
<id>[text(guid)]</id>
<exclusive>yes/no</exclusive>
</device>
</devices>
</methodcall>Server responses
(similar to the server initialize responses)
speak
The binary microphone data sent by the client wrapped as generic byte data (GenericByteData).
Client request
POST /imageserver?methodcall=speak HTTP/1.1
Content-Type: application/x-genericbytedata-octet-stream
Content-Length: [number]
X-RequestId: [number]
␍␊
[generic byte data – stream type] Server responses
(similar to the server initialize responses)
endspeak
See comment for beginspeak. Client request
Client request
POST /imageserver?methodcall=endspeak HTTP/1.1
Content-Length: 0
X-RequestId: [number]
␍␊ (<-- HTTP standard CR-LF)Server response (success)
HTTP/1.1 200 OK
Content-Length: 0
X-MethodName: endspeak
X-RequestId: [number]
␍␊ (<-- HTTP standard CR-LF)uninitialize
uninitialize closes any connected devices and resets the connection’s internal state. It will also be executed on the server if the socket connection to the client is lost or disconnected. This request might start a lengthy operation on the server which could lead to a delayed response.
Client request
POST /imageserver?methodcall=uninitialize HTTP/1.1
Content-Length: 0
X-RequestId: [number]
␍␊ (<-- HTTP standard CR-LF)Server response (success)
HTTP/1.1 200 OK
Content-Length: 0
X-MethodName: uninitialize
X-RequestId: [number]
␍␊ (<-- HTTP standard CR-LF)