speech-dispatcher: Direct SSIP Communication in C
4.1.11 Direct SSIP Communication in C
-------------------------------------
It might happen that you want to use some SSIP function that is not
available through a library or you may want to use an available function
in a different manner. (If you think there is something missing in a
library or you have some useful comment on the available functions,
please let us know.) For this purpose, there are a few functions that
will allow you to send arbitrary SSIP commands on your connection and
read the replies.
-- C API function: int spd_execute_command(SPDConnection* connection,
char *command);
You can send an arbitrary SSIP command specified in the parameter
'command'.
If the command is successful, the function returns a 0. If there
is no such command or the command failed for some reason, it
returns -1.
'connection' is the SPDConnection* connection created by
spd_open().
'command' is a null terminated string containing a full SSIP
command without the terminating sequence '\r\n'.
For example:
spd_execute_command(fd, "SET SELF RATE 60");
spd_execute_command(fd, "SOUND_ICON bell");
It's not possible to use this function for compound commands like
'SPEAK' where you are receiving more than one reply. If this is
your case, please see 'spd_send_data()'.
-- C API function: char* spd_send_data(SPDConnection* connection, const
char *message, int wfr);
You can send an arbitrary SSIP string specified in the parameter
'message' and, if specified, wait for the reply. The string can be
any SSIP command, but it can also be textual data or a command
parameter.
If 'wfr' (wait for reply) is set to SPD_WAIT_REPLY, you will
receive the reply string as the return value. If wfr is set to
SPD_NO_REPLY, the return value is a NULL pointer. If wfr is set to
SPD_WAIT_REPLY, you should always free the returned string.
'connection' is the SPDConnection* connection created by
spd_open().
'message' is a null terminated string containing a full SSIP
string. If this is a complete SSIP command, it must include the
full terminating sequence '\r\n'.
'wfr' is either SPD_WAIT_REPLY (integer value of 1) or SPD_NO_REPLY
(0). This specifies if you expect to get a reply on the sent data
according to SSIP. For example, if you are sending ordinary text
inside a 'SPEAK' command, you don't expect to get a reply, but you
expect a reply after sending the final sequence '\r\n.\r\n'.
For example (simplified by not checking and freeing the returned
strings):
spd_send_data(conn, "SPEAK", SPD_WAIT_REPLY);
spd_send_data(conn, "Hello world!\n", SPD_NO_REPLY);
spd_send_data(conn, "How are you today?!", SPD_NO_REPLY);
spd_send_data(conn, "\r\n.\r\n.", SPD_WAIT_REPLY);