Sync/stream subsystem events identify a specific change of state for either a master or slave stream handler. Some of these events do not have any effect on synchronization and merely indicate status of the data stream.
Two classes of events are defined: implicit and explicit. Implicit events are those events which all stream handlers must always support (such as end of stream or preroll complete). Explicit events are events which are supported only by some handlers (such as a custom event unique to a particular type of data). The application automatically receives notification of implicit events; however, the application must enable explicit events by using the SpiEnableEvent function if it wants to receive notification of any other events. Events remain enabled until they are disabled. The SSM and stream handlers are the only components that generate events.
The following table lists the events that are currently defined for the sync/stream subsystem. Stream handlers can also define new events for use as a communication mechanism between the stream handler and the application. Refer to the ulType and ulSubType fields in the EVCB data structure in the OS/2 Multimedia Programming Reference.
┌────────────────────────┬──────────┬────────────────────────────────────────┐ │Event │Data │Description │ │ │Structure │ │ ├────────────────────────┼──────────┼────────────────────────────────────────┤ │EVENT_CUE_DATA │DATA_EVCB │A cuepoint in terms of some specific │ │(Explicit) │ │piece of data in a stream. This event │ │ │ │can be enabled as a single event or as a│ │ │ │recurring event. │ ├────────────────────────┼──────────┼────────────────────────────────────────┤ │EVENT_CUE_TIME │TIME_EVCB │A cuepoint in terms of stream time from │ │(Explicit) │ │the start of the stream. This event can │ │ │ │be enabled as a single event or as a │ │ │ │recurring event. Recurring events are │ │ │ │events that are defined as a time │ │ │ │interval. An event is generated an each │ │ │ │occurrence of this time interval. Single│ │ │ │events remain enabled, even after they │ │ │ │are reported. In case the stream is │ │ │ │seeked backwards in time to a position │ │ │ │before a cuepoint and play is resumed, │ │ │ │the cuepoint will be reported again. │ ├────────────────────────┼──────────┼────────────────────────────────────────┤ │EVENT_CUE_TIME_PAUSE │TIME_EVCB │A cuepoint in terms of stream time from │ │(Explicit) │ │the start of the stream. This event will│ │ │ │cause the stream to be paused when the │ │ │ │cuepoint is reached. This event can be │ │ │ │enabled as a single event. │ ├────────────────────────┼──────────┼────────────────────────────────────────┤ │EVENT_DATAOVERRUN │EVCB │A stream handler detected a data │ │(Explicit) │ │overrun. Data could be lost in a │ │ │ │recording situation. │ ├────────────────────────┼──────────┼────────────────────────────────────────┤ │EVENT_DATAUNDERRUN │EVCB │A target stream handler detected a data │ │(Explicit) │ │underrun condition. There was no data │ │ │ │available to output to the output │ │ │ │device. Usually in this situation, the │ │ │ │target stream handler will attempt to │ │ │ │get another buffer and then pause it's │ │ │ │device. The target stream handler will │ │ │ │be re-started when more data is │ │ │ │available to be output. This condition │ │ │ │results in a break in the output data │ │ │ │stream. Interleaved data format can │ │ │ │cause underruns to occur when the end of│ │ │ │the data is reached, but the end of file│ │ │ │has not been reached. │ ├────────────────────────┼──────────┼────────────────────────────────────────┤ │EVENT_EOS (Implicit) │IMPL_EVCB │End of stream event. This event is │ │ │ │generated after the target stream │ │ │ │handler has consumed the last buffer in │ │ │ │the stream. This signals to the │ │ │ │application that the stream has │ │ │ │completed processing. │ ├────────────────────────┼──────────┼────────────────────────────────────────┤ │EVENT_ERROR (Implicit) │IMPL_EVCB │An error has occurred while streaming. │ ├────────────────────────┼──────────┼────────────────────────────────────────┤ │EVENT_PLAYLISTCUEPOINT │PLAYL_EVCB│A memory stream handler playlist │ │(Implicit) │ │cuepoint event. │ ├────────────────────────┼──────────┼────────────────────────────────────────┤ │EVENT_PLAYLISTMESSAGE │PLAYL_EVCB│A memory stream handler playlist │ │(Implicit) │ │message. │ ├────────────────────────┼──────────┼────────────────────────────────────────┤ │EVENT_QUEUE_OVERFLOW │IMPL_EVCB │Event queue overflow. Indicates that an │ │(Implicit) │ │event has been lost due to too many │ │ │ │events being generated. The application │ │ │ │(MCD) should use this event to clear any│ │ │ │waiting conditions. │ ├────────────────────────┼──────────┼────────────────────────────────────────┤ │EVENT_STREAM_STOPPED │IMPL_EVCB │The stream has been emptied or │ │(Implicit) │ │discarded. (See the SpiStopStream │ │ │ │function in the OS/2 Multimedia │ │ │ │Programming Reference.) │ ├────────────────────────┼──────────┼────────────────────────────────────────┤ │EVENT_SYNC_PREROLLED │IMPL_EVCB │All synchronized streams are prerolled. │ │(Implicit) │ │(See the SpiStartStream function in the │ │ │ │OS/2 Multimedia Programming Reference.) │ ├────────────────────────┼──────────┼────────────────────────────────────────┤ │EVENT_SYNCOVERRUN │OVRU_EVCB │A sync overrun has been detected in the │ │(Explicit) │ │stream. │ └────────────────────────┴──────────┴────────────────────────────────────────┘
The Sync/Stream Manager propagates events to the application through the media driver by doing a call-back to an event routine that the application registered with the SSM on an SpiCreateStream call. Use the event routine as if it were a second-level interrupt routine and do not attempt to do a lot of processing. The event routine is on a per-process basis; it receives only one process at a time. Therefore, when an event is sent to be processed, it must wait until the current event has completed processing.
Because there is only one EVCB for implicit events, it is a good idea to copy any needed information from the EVCB into local variables for processing by the event routine. The event routine has the following interface:
Event_Entry(PEVCB pEVCB, rc)