MMPM/2 Device Driver Reference:SHD Messages

The stream handler device (SHD) messages are provided by a stream handler through a single entry point, SHDEntryPoint, 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:

SHDEntryPoint
Each stream handler must provide this entry point, which is used for the PDD to communicate back to the stream handler.
 * 1) include 

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

rc = SHDEntryPoint(pCommon);

Parameter
pCommon (PSHD_COMMON) - input Pointer to SHD_COMMON.

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.

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.
 * 1) include       "os2.h"
 * 2) include       "os2me.h"
 * 3) 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.

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

Return Value
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.

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.

Example Code
The following code illustrates how to report an event to the stream handler.
 * 1) include       "os2.h"
 * 2) include       "os2me.h"
 * 3) 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.

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

Return Value
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.

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.

Example Code
The following code illustrates how to report an interrupt from a device.
 * 1) include       "os2.h"
 * 2) include       "os2me.h"
 * 3) 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! */