Jump to content

MMPM/2 Device Driver Reference:SHD Messages

From EDM2
Revision as of 22:32, 6 April 2016 by Reiknir (talk | contribs) (Created page with " === SHD Messages === The stream handler device (SHD) messages are provided by a stream handler through a single entry point, SHDEntryPoint, to a physical devi...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


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 ulFunctionfield, 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

Select an item: 

Syntax
Parameters 
Returns 
Remarks 
Example Code 
Glossary

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 - Syntax

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 - Parameters

pCommon(PSHD_COMMON) - input Pointer to SHD_COMMON.

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_INTcommand 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! */



SHDEntryPoint - Topics

Select an item: 

Syntax
Parameters 
Returns 
Remarks 
Example Code 
Glossary



SHD_REPORT_EVENT

Select an item: 

Syntax
Returns 
Remarks 
Example Code 
Glossary

This message reports an event to the stream handler.


pParmIn(PSHD_REPORTEVENT) A pointer to an SHD_REPORTEVENTdata structure.

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 Parameter - pParmIn

pParmIn(PSHD_REPORTEVENT) A pointer to an SHD_REPORTEVENTdata 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 - Syntax

This message reports an event to the stream handler.


pParmIn(PSHD_REPORTEVENT) A pointer to an SHD_REPORTEVENTdata structure.

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_EVENT - Topics

Select an item: 

Syntax
Returns 
Remarks 
Example Code 
Glossary



SHD_REPORT_INT

Select an item: 

Syntax
Returns 
Remarks 
Example Code 
Glossary

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.


pParmIn(PSHD_REPORTINT) A pointer to a SHD_REPORTINTdata structure.

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 Parameter - pParmIn

pParmIn(PSHD_REPORTINT) A pointer to a SHD_REPORTINTdata 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 - Syntax

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.


pParmIn(PSHD_REPORTINT) A pointer to a SHD_REPORTINTdata structure.

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



SHD_REPORT_INT - Topics

Select an item: 

Syntax
Returns 
Remarks 
Example Code 
Glossary


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

Retrieved from "https://www.edm2.com/index.php?title=MMPM/2_Device_Driver_Reference:SHD_Messages&oldid=25878"