SpiEnableEvent

The SpiEnableEvent function registers a specific event for a stream instance. Once enabled, the Sync/Stream Manager or a stream handler monitors the stream for the specified condition and notifies the application via the callback routine provided during SpiCreateStream.

Syntax

#include <os2.h>

rc = SpiEnableEvent(pevcb, phevent);

Parameters

pevcb (PEVCB) - input: A pointer to an Event Control Block (EVCB). This is a generic structure; the actual structure used (e.g., `TIME_EVCB`) depends on the type of event being enabled. It contains the stream handle, the handler ID responsible for detection, and event-specific thresholds.
phevent (PHEVENT) - output: A pointer to an HEVENT variable that receives the newly created event handle. This handle is used to later disable or modify the event.

Return Value

rc (ULONG) - returns

Return codes indicating success or the type of failure:

NO_ERROR: Success.
ERROR_INVALID_STREAM: Invalid stream handle within the EVCB.
ERROR_INVALID_EVENT: The specified event type is unrecognized.
ERROR_INVALID_EVCB: The information provided in the EVCB is invalid for this event type.
ERROR_TOO_MANY_EVENTS: System resources for events have been exhausted.
FAILURE: Stream handler-specific error.

Remarks

When an event condition is met, the Sync/Stream Manager triggers the `EventEntry` routine defined when the stream was created.

**Event Types**:
- **System-defined**: Range from 0x00000000 to 0x7FFFFFFF. Examples include:
  - `EVENT_CUE_TIME`: Triggers when a specific stream time is reached.
  - `EVENT_DATAUNDERRUN`: Triggers if the device runs out of data during playback.
  - `EVENT_SYNCOVERRUN`: Triggers if synchronization between master/slave streams is lost.
- **User-defined**: Range from 0x80000000 to 0xFFFFFFFF. These are defined by specific stream handlers.
**Scope**: The event is active only for the stream instance specified in the `hstream` field of the EVCB.
**Persistence**: Unless specified otherwise in the `ulFlags` (e.g., `EVENT_SINGLE`), events remain active until explicitly removed via SpiDisableEvent.

Example Code

The following code demonstrates enabling a cue point event to trigger after 60 seconds (60,000 milliseconds) of stream playback.

#include <os2.h>
#include <os2me.h>

ULONG      ulRC;          /* Error return code      */
HID        hidTarget;     /* Target handler ID      */
HSTREAM    hStream;       /* Stream handle          */
TIME_EVCB  timeevcb;      /* Time event control     */
HEVENT     hevent;        /* Event handle           */

/* ... Stream is created via SpiCreateStream ... */

/* Initialize the Time Event Control Block */
timeevcb.ulType = EVENT_CUE_TIME;
timeevcb.ulFlags = EVENT_SINGLE;     /* Trigger only once           */
timeevcb.hstream = hStream;
timeevcb.hid = hidTarget;            /* Target handler monitors time */
timeevcb.mmtimeStream = 60000;       /* Trigger at 60,000ms         */

/* Enable the event */
ulRC = SpiEnableEvent((PEVCB)&timeevcb, &hevent);

if (ulRC) {
    return (ulRC); /* Error handling */
}

Related Functions

Related Messages

SHC_ENABLE_EVENT