MMPM/2 Device Driver Reference:SHD Messages: Difference between revisions
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..." |
mNo edit summary |
||
(6 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
{{MMPM2DDRef}} | |||
{{IBM-Reprint}} | |||
The stream handler device (SHD) messages are provided by a stream handler through a single entry point, [[#SHDEntryPoint|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 stream handler device (SHD) messages are provided by a stream handler through a single entry point, [[ | |||
The following table lists the SHD messages: | The following table lists the SHD messages: | ||
{|class="wikitable" | |||
!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. | Each stream handler must provide this entry point, which is used for the PDD to communicate back to the stream handler. | ||
<pre> | |||
#include <os2me.h> | |||
PSHD_COMMON pCommon; /* Pointer to SHD_COMMON. */ | |||
ULONG rc; /* Return codes. */ | |||
PSHD_COMMON pCommon; /* | |||
ULONG rc; /* | |||
rc = SHDEntryPoint(pCommon); | |||
</pre> | |||
=== Parameter === | |||
'''pCommon''' ([[MMPM/2 Device Driver Reference:Data Types#SHD_COMMON|PSHD_COMMON]]) - input Pointer to SHD_COMMON. | |||
=== Return Value === | |||
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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 [[MMPM/2 Device Driver Reference:Data Types#SHD_REPORT_INT|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. | The following code illustrates how to access this entry point, which is used for the PDD to communicate back to the stream handler. | ||
<pre> | |||
<pre | #include "os2.h" | ||
#include | #include "os2me.h" | ||
#include | #include "shdd.h" | ||
ULONG ulRC; /* Error return code */ | ULONG ulRC; /* Error return code */ | ||
Line 122: | Line 52: | ||
PSHDFN pshdfn; /* Pointer to SHD entry point */ | PSHDFN pshdfn; /* Pointer to SHD entry point */ | ||
ULONG ulStreamTime; /* Stream time */ | ULONG ulStreamTime; /* Stream time */ | ||
. | . | ||
. | . | ||
Line 134: | Line 63: | ||
shdpb.ulStreamTime = ulStreamTime; | shdpb.ulStreamTime = ulStreamTime; | ||
if (ulRC = pshdfn (& | if (ulRC = pshdfn (&shdpb)) | ||
return (ulRC); /* error! */ | return (ulRC); /* error! */ | ||
</pre> | |||
==SHD_REPORT_EVENT== | |||
This message reports an event to the stream handler. | This message reports an event to the stream handler. | ||
=== Parameter=== | |||
'''pParmIn''' ([[MMPM/2 Device Driver Reference:Data Types#SHD_REPORTEVENT|PSHD_REPORTEVENT]]) A pointer to an SHD_REPORTEVENT data structure. | |||
=== Return Value=== | |||
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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 [[MMPM/2 Device Driver Reference:DDCMD Messages#DDCMD_CONTROL|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. | |||
<pre> | |||
#include "os2.h" | |||
#include "os2me.h" | |||
#include "shdd.h" | |||
=== | |||
The following code illustrates how to report an event to the stream handler . | |||
<pre | |||
#include | |||
#include | |||
ULONG ulRC; /* Error return code */ | ULONG ulRC; /* Error return code */ | ||
Line 262: | Line 102: | ||
PSHDFN pshdfn; /* Pointer to SHD entry point */ | PSHDFN pshdfn; /* Pointer to SHD entry point */ | ||
ULONG ulStreamTime; /* Stream time */ | ULONG ulStreamTime; /* Stream time */ | ||
. | . | ||
. | . | ||
Line 274: | Line 113: | ||
shdpb.ulStreamTime = ulStreamTime; | shdpb.ulStreamTime = ulStreamTime; | ||
if (ulRC = pshdfn (& | if (ulRC = pshdfn (&shdpb)) | ||
return (ulRC); /* error! */ | return (ulRC); /* error! */ | ||
</pre> | |||
==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. | 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''' ([[MMPM/2 Device Driver Reference:Data Types#SHD_REPORTINT|PSHD_REPORTINT]]) A pointer to a SHD_REPORTINT data structure. | |||
=== Return Value=== | |||
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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. | |||
=== | |||
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. | 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. | ||
Line 396: | Line 147: | ||
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. | 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. | The following code illustrates how to report an interrupt from a device. | ||
<pre> | |||
<pre | #include "os2.h" | ||
#include | #include "os2me.h" | ||
#include | #include "shdd.h" | ||
ULONG ulRC; /* Error return code */ | ULONG ulRC; /* Error return code */ | ||
Line 414: | Line 160: | ||
PVOID pBuffer; /* Pointer to buffer */ | PVOID pBuffer; /* Pointer to buffer */ | ||
ULONG ulStreamTime; /* Stream time in millisecs */ | ULONG ulStreamTime; /* Stream time in millisecs */ | ||
. | . | ||
. | . | ||
Line 428: | Line 173: | ||
shdpb.ulStreamTime = ulStreamTime; | shdpb.ulStreamTime = ulStreamTime; | ||
if (ulRC = pshdfn (& | if (ulRC = pshdfn (&shdpb)) | ||
return (ulRC); /* error! */ | return (ulRC); /* error! */ | ||
</pre> | |||
[[Category: | [[Category:MMPM/2 Device Driver Reference]] | ||
Latest revision as of 21:29, 16 October 2018
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
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);
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.
#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.
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.
#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.
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.
#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! */