speech-dispatcher: Event Notification and Index Marking in C
4.1.9 Event Notification and Index Marking in C
-----------------------------------------------
When the SSIP connection is run in asynchronous mode, it is possible to
register callbacks for all the SSIP event notifications and index mark
Index Marking::
-- Variable: C API type SPDNotification
'SPDNotification' is an enum type that represents the possible base
notification types that can be assigned to a message.
typedef enum{
SPD_BEGIN = 1,
SPD_END = 2,
SPD_INDEX_MARKS = 4,
SPD_CANCEL = 8,
SPD_PAUSE = 16,
SPD_RESUME = 32
}SPDNotification;
There are currently two types of callbacks in the C API.
-- Variable: C API type SPDCallback
'void (*SPDCallback)(size_t msg_id, size_t client_id,
SPDNotificationType state);'
This one is used for notifications about the events: 'BEGIN',
'END', 'PAUSE' and 'RESUME'. When the callback is called, it
provides three parameters for the event.
'msg_id' unique identification number of the message the
notification is about.
'client_id' specifies the unique identification number of the
client who sent the message. This is usually the same connection
as the connection which registered this callback, and therefore
uninteresting. However, in some special cases it might be useful
to register this callback for other SSIP connections, or register
the same callback for several connections originating from the same
application.
'state' is the 'SPD_Notification' type of this notification. ⇒
SPDNotification.
-- Variable: C API type SPDCallbackIM
'void (*SPDCallbackIM)(size_t msg_id, size_t client_id,
SPDNotificationType state, char *index_mark);'
'SPDCallbackIM' is used for notifications about index marks that
have been reached in the message. (A way to specify index marks is
e.g. through the SSML element <mark/> in ssml mode.)
The syntax and meaning of these parameters are the same as for
⇒SPDCallback except for the additional parameter
'index_mark'.
'index_mark' is a NULL terminated string associated with the index
mark. Please note that this string is specified by client
application and therefore it needn't be unique.
One or more callbacks can be supplied for a given 'SPDConnection*'
connection by assigning the values of pointers to the appropriate
functions to the following connection members:
SPDCallback callback_begin;
SPDCallback callback_end;
SPDCallback callback_cancel;
SPDCallback callback_pause;
SPDCallback callback_resume;
SPDCallbackIM callback_im;
There are three settings commands which will turn notifications on
and off for the current SSIP connection and cause the callbacks to be
called when the event is registered by Speech Dispatcher.
-- C API function: int spd_set_notification_on(SPDConnection*
connection, SPDNotification notification);
-- C API function: int spd_set_notification_off(SPDConnection*
connection, SPDNotification notification);
-- C API function: int spd_set_notification(SPDConnection* connection,
SPDNotification notification, const char* state);
These functions will set the notification specified by the
parameter 'notification' on or off (or to the given value)
respectively. Note that it is only safe to call these functions
after the appropriate callback functions have been set in the
'SPDCallback' structure. Doing otherwise is not considered an
error, but the application might miss some events due to callback
functions not being executed (e.g. the client might receive an
'END' event without receiving the corresponding 'BEGIN' event in
advance.
'connection' is the SPDConnection* connection created by
spd_open().
'notification' is the requested type of notifications that should
be reported by SSIP. ⇒SPDNotification. Note that also '|'
combinations are possible, as illustrated in the example below.
'state' must be either the string "on" or "off", for switching the
given notification on or off.
The following example shows how to use callbacks for the simple
purpose of playing a message and waiting until its end. (Please note
that checks of return values in this example as well as other code not
directly related to index marking, have been removed for the purpose of
clarity.)
#include <semaphore.h>
sem_t semaphore;
/* Callback for Speech Dispatcher notifications */
void end_of_speech(size_t msg_id, size_t client_id, SPDNotificationType type)
{
/* We don't check msg_id here since we will only send one
message. */
/* Callbacks are running in a separate thread, so let the
(sleeping) main thread know about the event and wake it up. */
sem_post(&semaphore);
}
int
main(int argc, char **argv)
{
SPDConnection *conn;
sem_init(&semaphore, 0, 0);
/* Open Speech Dispatcher connection in THREADED mode. */
conn = spd_open("say","main", NULL, SPD_MODE_THREADED);
/* Set callback handler for 'end' and 'cancel' events. */
conn->callback_end = con->callback_cancel = end_of_speech;
/* Ask Speech Dispatcher to notify us about these events. */
spd_set_notification_on(conn, SPD_END);
spd_set_notification_on(conn, SPD_CANCEL);
/* Say our message. */
spd_sayf(conn, SPD_MESSAGE, "%s", argv[1]);
/* Wait for 'end' or 'cancel' of the sent message.
By SSIP specifications, we are guaranteed to get
one of these two eventually. */
sem_wait(&semaphore);
return 0;
}
Info Catalog
speech-dispatcher: Information Retrieval Commands in C
speech-dispatcher: C API
speech-dispatcher: History Commands in C