SHDEntryPoint

Each stream handler must provide the SHDEntryPoint entry point, which is used by the Physical Device Driver (PDD) to communicate back to the stream handler.

Syntax

ULONG SHDEntryPoint(PSHD_COMMON pCommon);

Parameters

pCommon (PSHD_COMMON) - input

A pointer to an SHD_COMMON structure. This structure generally contains the function code and the necessary parameters for the specific request.

Return Value

rc (ULONG) - returns

Return codes indicating success or the type of failure:

• NO_ERROR: Successful.
• ERROR_INVALID_FUNCTION: Invalid function requested.
• FAILURE: An SHD message-specific error return code.

Remarks

Device driver stream handlers receive commands from PDDs to report events and interrupts. These Stream Handler Device (SHD) helper commands are provided through the SHDEntryPoint. This entry point is specifically used for the PDD to call back to the stream handler.

For example, the PDD can send an SHD_REPORT_INT command to the stream handler to report status, indicate that a buffer is full, or specify that an additional buffer is required.

Related Functions

• SHD_REPORT_EVENT
• SHD_REPORT_INT

Example Code

The following code illustrates how to access this entry point to report a cue point (event) from a PDD back 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                */

  /* ... Setup handles and pointers ... */

  /*----------------------------------------------------------------------*/
  /* 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;

  /* Call the entry point via the function pointer */
  ulRC = pshdfn((PSHD_COMMON)&shdpb);

  if (ulRC)
  {
     return (ulRC);    /* error! */
  }