SHD_REPORT_EVENT
The SHD_REPORT_EVENT message is used by a Physical Device Driver (PDD) to report the detection of a specific event (such as a cue point) back to the stream handler.
Syntax
#include <os2.h> rc = SHDEntryPoint(pParmIn);
Parameters
- pParmIn (PSHD_REPORTEVENT) - input
- A pointer to an SHD_REPORTEVENT data structure containing the stream handle, event handle, and the stream time at which the event occurred.
Return Value
- rc (ULONG) - returns
- Return codes indicating success or the type of failure:
- NO_ERROR: Success.
- ERROR_INVALID_FUNCTION: Illegal function requested.
- ERROR_INVALID_STREAM: Invalid stream handle.
- ERROR_INVALID_EVENT: Invalid event handle.
- FAILURE: Stream-handler-specific error return code.
Remarks
This message provides the mechanism for a PDD to perform asynchronous callback notification for event detection.
Typically, the workflow is as follows:
- The stream handler enables event monitoring in the PDD using DDCMD_CONTROL with the DDCMD_ENABLE_EVENT command.
- If the PDD supports hardware-level or driver-level event detection, it monitors the stream time.
- Upon reaching the specified cue point or event criteria, the PDD calls the stream handler's SHDEntryPoint using this SHD_REPORT_EVENT message.
- The PDD must ensure that both the hevent (event handle) and ulStreamTime are accurately populated in the parameter block.
Example Code
The following code illustrates how a PDD reports a detected cue point to the stream handler.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
HEVENT hevent; /* Event handle */
SHD_REPORTEVENT shdpb; /* Parameter block */
PSHDFN pshdfn; /* Pointer to SHD entry point */
ULONG ulStreamTime; /* Stream time */
/* ... Assume handles and function pointer are valid ... */
/*----------------------------------------------------------------------*/
/* Report a cue point to the stream handler for a stream instance. */
/*----------------------------------------------------------------------*/
shdpb.ulFunction = SHD_REPORT_EVENT;
shdpb.hstream = hstream;
shdpb.hevent = hevent;
shdpb.ulStreamTime = ulStreamTime;
ulRC = pshdfn(&shdpb);
if (ulRC) {
return (ulRC); /* error! */
}