ssip: General Rules
3 General Rules
***************
SSIP communicates with the clients through a defined set of text
commands, in the usual manner for common Internet protocols. The
characters sent through the Speech Synthesis Interface Protocol are
encoded using the UTF-8 encoding.
Each SSIP command, unless specified otherwise, consists of exactly
one line. The line is sent in the following format:
COMMAND ARG ...
where COMMAND is a case insensitive command name and ARGs are its
arguments separated by spaces. The command arguments which come from a
defined set of values are case insensitive as well. The number of
arguments is dependent on the particular command and there can be
commands having no arguments.
All lines of SSIP input and output must be ended with a pair of
carriage return and line feed characters, in that order.
When you connect to Speech Server, you should at least set your
client name, through the 'SET SELF CLIENT_NAME' command (⇒Parameter
Setting Commands). This is important to get a proper identification
of your client -- to allow managing it from the control center
application and to identify it in a message history browser. You might
want to set other connection parameters as well. Look for more details
in ⇒Parameter Setting Commands.
An SSIP connection is preferably closed by issuing the 'QUIT'
command, see ⇒Other Commands.
SSIP is a synchronous protocol -- you send commands and only after a
complete response from SSIP arrives back are you allowed to send the
next command. Usually, the SSIP connection remains open during the
whole run of the particular client application. If you close the
connection and open it again, you must set all the previously set
parameters again, SSIP doesn't store session parameters between
connections.
The protocol allows you to perform commands influencing other
currently connected or previously connected clients. This allows you to
write a control application managing or browsing all the messages
received by the current Speech Server process. The mechanism is
completely relaxed, there are no restrictions on managing some aspects
of sound output for other users, however, there is a mechanism to
prevent one user from seeing history messages of another user.
Some of the commands (⇒Speech Output Control Commands and
⇒Parameter Setting Commands) take an argument in the form:
{ ID | all | self }
where the value can be the 'id' of the connection the command should
be performed on (a positive number), the string 'all' to act on all
clients of this server or 'self' to act on the connection itself.
Unless you are writing a special client for managing Speech Server or
unless you have specific needs, you should only use the 'self' value for
this argument.
Not all parameter setting commands may receive all kinds of the first
parameter defined above, for instance, some of them may receive only
'self'.
SSIP replies have the following format:
CCC-line 1
CCC-line 2
...
CCC-line N-1
DDD line N
where N is a positive integer, and CCC and DDD are three-digit long
numeric codes identifying the result of the command. The last line
determines the overall result of the command. The result code is
followed by an English message describing the result of the action in a
human readable form.