MMPM/2 Device Driver Reference:SHD Messages

SHD Messages

The stream handler device (SHD) messages are provided by a stream handler through a single entry point, #SHDEntryPointSHDEntryPoint, to a physical device driver. For this interface, all pointers are 16:16 pointers; this enables the current 16-bit device-driver model to be used for stream handlers. There are two SHD messages. The message number must be used in the ulFunction field, of the parameter structure passed in the call, to indicate which message is being requested by the stream handler.

The following table lists the SHD messages:

/-----------------------------------------------------------------\
|Message |Message             |Description                        |
|Number  |                    |                                   |
|--------+--------------------+-----------------------------------|
|1L      |SHD_REPORT_EVENT    |Reports an event to the stream     |
|        |                    |handler.                           |
|--------+--------------------+-----------------------------------|
|0L      |SHD_REPORT_INT      |Reports an interrupt from a device.|
\-----------------------------------------------------------------/

SHDEntryPoint

Each stream handler must provide this entry point, which is used for the PDD to communicate back to the stream handler.

#include <os2me.h>

PSHD_COMMON    pCommon;  /*  Pointer to SHD_COMMON. */
ULONG          rc;       /*  Return codes. */

rc = SHDEntryPoint(pCommon);

SHDEntryPoint Parameter - pCommon

pCommon (PSHD_COMMON) - input Pointer to SHD_COMMON.

SHDEntryPoint Return Value - rc

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.

SHDEntryPoint - 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.

SHDEntryPoint - Example Code

The following code illustrates how to access this entry point, which is used for the PDD to communicate 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                */

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

  if (ulRC = pshdfn (&shdpb))
    return (ulRC);    /* error! */

SHD_REPORT_EVENT

This message reports an event to the stream handler.

SHD_REPORT_EVENT Parameter - pParmIn

pParmIn (PSHD_REPORTEVENT) A pointer to an SHD_REPORTEVENT data structure.

SHD_REPORT_EVENT Return Value - rc

rc (ULONG) 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.

SHD_REPORT_EVENT - Remarks

This message is a mechanism for the physical device driver to report its own event (cue point) detection. The stream handler will call the PDD with an event via DDCMD_CONTROL (DDCMD_ENABLE_EVENT) and the PDD will monitor the stream time for this event (if the PDD supports event detection). When the event is detected, the PDD will call back the stream handler and report this event via this message. The handle to the event and stream time must be set.

SHD_REPORT_EVENT - Example Code

The following code illustrates how to report an event 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                */

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

  if (ulRC = pshdfn (&shdpb))
    return (ulRC);    /* error! */

SHD_REPORT_INT

This message is used by the physical device driver to report interrupts from a device and indicate that a new buffer is needed for consumption.

SHD_REPORT_INT Parameter - pParmIn

pParmIn (PSHD_REPORTINT) A pointer to a SHD_REPORTINT data structure.

SHD_REPORT_INT Return Value - rc

rc (ULONG) Return codes indicating success or type of failure:

• NO_ERROR

Success.

• ERROR_INVALID_FUNCTION

Illegal function requested.

• ERROR_INVALID_STREAM

Invalid stream handle.

• ERROR_DEVICE_UNDERRUN

There was a device data underrun.

• ERROR_DEVICE_OVERRUN

There was a device data overrun.

• FAILURE

Stream-handler-specific error return code.

SHD_REPORT_INT - Remarks

This message is a mechanism for the physical device driver to return status , indicate that the buffer has been consumed, or indicate that a new buffer is needed.

When status is returned, you will know whether the playback or record was successful or if there was an error condition. Error conditions for playback are known as underruns, which means the device is not getting data fast enough. Error conditions for records are called overruns, which means the device is generating data faster than empty buffers become available. This might result in a data loss situation. For example, the device is constantly bringing in data from the analog ports of the adapter and converting it to digital data. If the device does not have any empty buffers to store the digital data, the data is lost.

If you report an underrun under Warp and want the stream handler to pause the device, you should report the ERROR_DEVICE_UNDERRUN as well as the SHD_ WRITE_COMPLETE flags.

The VSD must return buffers in the order they were sent and should not hold on to any buffers. Failure to return buffers could result in application hangs.

SHD_REPORT_INT - Example Code

The following code illustrates how to report an interrupt from a device.

#include        "os2.h"
#include        "os2me.h"
#include        "shdd.h"

  ULONG           ulRC;                   /* Error return code          */
  HSTREAM         hstream;                /* Stream handle              */
  SHD_REPORTINT   shdpb;                  /* Parameter block            */
  PSHDFN          pshdfn;                 /* Pointer to SHD entry point */
  PVOID           pBuffer;                /* Pointer to buffer          */
  ULONG           ulStreamTime;           /* Stream time in millisecs   */

                            .
                            .
                            .
/*----------------------------------------------------------------------*/
/*  Report a read has completed.                                        */
/*----------------------------------------------------------------------*/
  shdpb.ulFunction = SHD_REPORT_INT;
  shdpb.hstream = hstream;
  shdpb.pBuffer = pBuffer;
  shdpb.ulFlag = SHD_READ_COMPLETE;
  shdpb.ulStatus = LengthRecordedBuffer;
  shdpb.ulStreamTime = ulStreamTime;

  if (ulRC = pshdfn (&shdpb))
    return (ulRC);    /* error! */

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation