(Page 3 of 5 in this chapter)

NaturalText Events

All events in the CT Access environment are represented as a C data structure as shown below: typedef struct_DISP_EVENT { DWORD id; /* event id (LIBEVN_xxx in 'libdef.h') */ CTAHD ctahd; /* CTA context handle */ DWORD timestamp; /* timestamp */ DWORD userid; /* use-supplied id */ DWORD size; /* size of buffer if buffer is not NULL */ /* otherwise, may contain event-specific data */ void *buffer; /* buffer pointer */ DWORD value; /* Event status or event-specific data */ DWORD reserved; /* must be 0 */ } CTA_EVENT;
This structure, returned by ctaWaitEvent, informs applications which events occurred on which CT Access contexts, and provides additional information specific to the events. The LIB prefix in LIBEVN relates events to specific Natural MicroSystems functions libraries. For example, the CTA prefix indicates CT Access while TTS indicates NaturalText.
The event structure contains the following fields:
:

Field

Description

id

Contains an event code defined in the library header file. All NaturalRecognition events are prefixed with TTSEVN_ (e.g., TTSEVN_SOMETHING_HAPPENED).

ctahd

Contains the CT Access context handle (returned from ctaCreateContext).

timestamp

Contains the time when the event was created in milliseconds since midnight, January 1, 1970, modulo 49 days. The resolution for AG board events is 10 milliseconds.

userid

Contains the user-supplied id. This field is unaltered by CT Access and facilitates asynchronous programming. Its purpose is to correlate a CT Access context with an application object/CT Access context when events occur.

value

This is an event-specific value. This field can hold a reason code or an error code.

size

The size (bytes) of the area pointed to by buffer. If the buffer is NULL, this field may be used to hold an event-specific value.

buffer

This field points to data returned with the event. The field contains an application process address and the event's size field contains the actual size of the buffer. (Not used by NaturalText).
NaturalText DONE Event
The only NaturalText-specific event is TTS_SPEAK_DONE. As with all DONE events in the CT Access environment, it indicates that a function has completed executing. Examine the reason code or error code stored in the value field of the event for further information about the cause of the event, or the result of the function's execution.
The following NaturalText reason codes may appear in the value fields of the TTS_SPEAK_DONE event:

Reason

Description

CTA_REASON_FINISHED

Function execution has finished successfully.

CTA_REASON_STOPPED

Text-to-speech has stopped because ttsStop has successfully executed.

Field	Description
id	Contains an event code defined in the library header file. All NaturalRecognition events are prefixed with TTSEVN_ (e.g., TTSEVN_SOMETHING_HAPPENED).
ctahd	Contains the CT Access context handle (returned from `ctaCreateContext`).
timestamp	Contains the time when the event was created in milliseconds since midnight, January 1, 1970, modulo 49 days. The resolution for AG board events is 10 milliseconds.
userid	Contains the user-supplied id. This field is unaltered by CT Access and facilitates asynchronous programming. Its purpose is to correlate a CT Access context with an application object/CT Access context when events occur.
value	This is an event-specific value. This field can hold a reason code or an error code.
size	The size (bytes) of the area pointed to by buffer. If the buffer is NULL, this field may be used to hold an event-specific value.
buffer	This field points to data returned with the event. The field contains an application process address and the event's size field contains the actual size of the buffer. (Not used by NaturalText).

Reason	Description
CTA_REASON_FINISHED	Function execution has finished successfully.
CTA_REASON_STOPPED	Text-to-speech has stopped because ttsStop has successfully executed.

(Page 3 of 5 in this chapter)

tech_support@nmss.com