speech-dispatcher: Initializing and Terminating in C
4.1.1 Initializing and Terminating
----------------------------------
-- C API function: SPDConnection* spd_open(const char* client_name,
const char* connection_name, const char* user_name,
SPDConnectionMode connection_mode)
Opens a new connection to Speech Dispatcher and returns a socket
file descriptor you will use to communicate with Speech Dispatcher.
The socket file descriptor is a parameter used in all the other
functions. It now uses local communication via inet sockets. See
'spd_open2' for more details.
The three parameters 'client_name', 'connection_name' and
'username' are there only for informational and navigational
purposes, they don't affect any settings or behavior of any
functions. The authentication mechanism has nothing to do with
'username'. These parameters are important for the user when he
wants to set some parameters for a given session, when he wants to
browse through history, etc. The parameter 'connection_mode'
specifies how this connection should be handled internally and if
event notifications and index marking capabilities will be
available.
'client_name' is the name of the client that opens the connection.
Normally, it should be the name of the executable, for example
"lynx", "emacs", "bash", or "gcc". It can be left as NULL.
'connection_name' determines the particular use of that connection.
If you use only one connection in your program, this should be set
to "main" (passing a NULL pointer has the same effect). If you use
two or more connections in your program, their 'client_name's
should be the same, but 'connection_name's should differ. For
example: "buffer", "command_line", "text", "menu".
'username' should be set to the name of the user. Normally, you
should get this string from the system. If set to NULL, libspeechd
will try to determine it automatically by g_get_user_name().
'connection_mode' has two possible values: 'SPD_MODE_SINGLE' and
'SPD_MODE_THREADED'. If the parameter is set to
'SPD_MODE_THREADED', then 'spd_open()' will open an additional
thread in your program which will handle asynchronous SSIP replies
and will allow you to use callbacks for event notifications and
index marking, allowing you to keep track of the progress of
speaking the messages. However, you must be aware that your
program is now multi-threaded and care must be taken when
using/handling signals. If 'SPD_MODE_SINGLE' is chosen, the
library won't execute any additional threads and SSIP will run only
as a synchronous protocol, therefore event notifications and index
marking won't be available.
It returns a newly allocated SPDConnection* structure on success,
or 'NULL' on error.
Each connection you open should be closed by spd_close() before the
end of the program, so that the associated connection descriptor is
closed, threads are terminated and memory is freed.
-- C API function: SPDConnection* spd_open2(const char* client_name,
const char* connection_name, const char* user_name,
SPDConnectionMode connection_mode, const SPDConnectionAddress
* address, int autospawn, char **error_result)
Opens a new connection to Speech Dispatcher and returns a socket
file descriptor. This function is the same as 'spd_open' except
that it gives more control of the communication method and
autospawn functionality as described below.
'address' designates the address to which this should connect to.
Setting this to NULL lets libspeechd use the default address (as
reported by 'spd_get_default_address'). The 'method' field of
'address' can be either 'SPD_METHOD_UNIX_SOCKET' or
'SPD_METHOD_INET_SOCKET'. In the Unix case, the 'unix_socket_name'
field must be set to the Unix path. In the Inet case, the
'inet_socket_host' field must be set to the Inet host, and the
'inet_socket_port' must be set to the TCP port to be used (in host
endianness). The 'dbus_bus' is currently unused.
By default, unix socket communication should be preferred, but inet
sockets are necessary for cross-network communication.
'autospawn' is a boolean flag specifying whether the function
should try to autospawn (autostart) the Speech Dispatcher server
process if it is not running already. This is set to 1 by default,
so this function should normally not fail even if the server is not
yet running.
'error_result' has to be the address of a 'char*' variable, which
will be filled with an error message if some error occurs. That
message must be freed with 'free'.
-- C API function: int spd_get_client_id(SPDConnection *connection)
Get the client ID.
'connection' is the SPDConnection* connection created by
spd_open().
It returns the client ID of the connection.
-- C API function: void spd_close(SPDConnection *connection)
Closes a Speech Dispatcher socket connection, terminates associated
threads (if necessary) and frees the memory allocated by
spd_open(). You should close every connection before the end of
your program.
'connection' is the SPDConnection connection obtained by
spd_open().
Info Catalog
speech-dispatcher: C API
speech-dispatcher: C API
speech-dispatcher: Speech Synthesis Commands in C