ISpNotifySink (SAPI 5.3)

Microsoft Speech API 5.3

ISpNotifySink

In both speech synthesis and speech recognition, applications receive notifications when words have been spoken or when phrases have been recognized. SAPI components that generate notifications implement an ISpNotifySource.

The ISpNotifySource and ISpNotifySink interfaces alone only provide a mechanism for a notification but no information on the events that caused the notification. With an ISpEventSource object, an application can retrieve information about the events that caused the notification. An ISpEventSource also provides the mechanism to filter and queue events. By default, an application (really an ISpNotifySink) receives no notifications from ISpEventSource until SetInterests has been called to specify on which events to notify or queue.

When an application is notified of an event that is not queued, an application will take measures based on which event sink is receiving the notification. From context an application might know exactly what it needs to do, or it may need to interact with the components which sent the notifications. If an application is notified of an event that is queued, the application will call ISpEventSource::GetEvents to retrieve the actual events that caused a notification.

When to Implement

Implement this interface only if the application can take advantage of the slightly reduced latency of a free-threaded notification.  Most applications should use one of the simplified notification mechanisms in ISpEventSource instead of implementing this interface directly. Free-threaded notifications are difficult to implement without deadlocking the system. Furthermore, other notification mechanisms require less code on the part of the developer. The application needs to handle free-threaded notifications and implement the ISpNotifySink interface when an ISpNotifySink object is to be notified.

Because free-threaded notifications can occur on any thread, at any point during execution, they are extremely prone to deadlocks and re-entrance problems. The only interface that can be called on an event source object is ISpEventSource::GetEvents. If the ISpNotifySink interface is implemented directly, the code should only use some mechanism to signal another thread to process the notification (for example, a Win32 event or an I/O completion port), and, if needed, call ISpEventSource::GetEvents. Do not call any other methods.

Methods in Vtable Order