MMPM/2 Device Driver Reference:SHD Messages

From EDM2
Jump to: navigation, search
MMPM/2 Device Driver Reference
  1. Adding Support for Audio and Video Adapters
  2. Audio Physical Device Driver Template
  3. Audio Virtual Device Driver Template
  4. MAD16 PDD and VDD Sample Device Drivers
  5. PDD Sample for Video Capture Adapters
  6. PDD Sample for MPEG Video Playback Devices
  7. Audio Sample for Vendor-Specific Drivers
  8. Using the High-Resolution Timer
  9. Real-Time MIDI Subsystem
  10. Audio Device Driver Exerciser (PMADDE) Tool
  11. AP2/P2STRING Tool
  12. Ultimotion Data Stream Specification
  13. DDCMD Messages
  14. SHD Messages
  15. Vendor-Specific Driver Commands
  16. IOCtl Functions
  17. Data Types
  18. Types of MIDI Messages
  19. Notices
  20. Glossary

By IBM

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

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:

Message Number Message Description
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! */