SpiDisableEvent

The SpiDisableEvent function disables event notification for a specific event handle. It removes the event from the system, preventing it from being detected or reported for the associated stream instance.

Syntax

#include <os2.h>

rc = SpiDisableEvent(hevent);

Parameters

hevent (HEVENT) - input

The unique handle identifying the event to be disabled. This handle was returned by a previous call to SpiEnableEvent.

Return Value

rc (ULONG) - returns

Return codes indicating success or the type of failure:

• NO_ERROR: Success.
• ERROR_INVALID_FUNCTION: Invalid function requested.
• ERROR_INVALID_EVENT: The provided event handle is not valid.
• ERROR_INVALID_REQUEST: Attempted to disable an implicit event (implicit events are managed by the Sync/Stream Manager and cannot be manually disabled via this function).
• FAILURE: Stream handler-specific error return code.

Remarks

Issuing this function effectively terminates the lifecycle of an event for a stream instance.

• **Handle Invalidation**: After this call, the `hevent` handle is no longer valid and cannot be reused.
• **Manual Cleanup**: Events in the OS/2 Multimedia System are not automatically removed once they are triggered or reported. The application or Media Control Driver (MCD) must explicitly call SpiDisableEvent to clean up resources.
• **Detection Termination**: Once removed, the Sync/Stream Manager and the physical device driver (PDD) stop monitoring for the conditions associated with that event (e.g., a specific cue point or stream time).

Example Code

The following code fragment shows how to disable an event after it is no longer needed for stream monitoring.

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

ULONG   ulRC;          /* Error return code */
HEVENT  heventTime;    /* Event handle      */

/* ... Stream is created and an event is enabled via SpiEnableEvent ... */

/*------------------------------------------------------------------*/
/* Do other processing, such as waiting for the event to trigger    */
/*------------------------------------------------------------------*/

/*------------------------------------------------------------------*/
/* Now disable the event explicitly to free system resources        */
/*------------------------------------------------------------------*/
ulRC = SpiDisableEvent(heventTime);

if (ulRC) {
  /* Handle the error if the event handle was invalid or implicit */
  return (ulRC);
}

Related Functions

• SpiEnableEvent
• SpiCreateStream

Related Messages

• SHC_DISABLE_EVENT