SHD_REPORT_INT
The SHD_REPORT_INT message is used by a Physical Device Driver (PDD) or Vendor Specific Driver (VSD) to report interrupts from a hardware device. This message indicates that a buffer has been processed (consumed or filled) and signaling that a new buffer is required for continued operation.
Syntax
#include <os2.h> rc = SHDEntryPoint(pParmIn);
Parameters
- pParmIn (PSHD_REPORTINT) - input
- A pointer to an SHD_REPORTINT data structure containing the stream handle, the address of the buffer being returned, status flags, and the current stream time.
Return Value
- rc (ULONG) - returns
- 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: A playback data underrun occurred.
- ERROR_DEVICE_OVERRUN: A recording data overrun occurred.
- FAILURE: Stream-handler-specific error return code.
Remarks
This message is the primary mechanism for a device driver to communicate operational status and manage buffer flow.
- **Buffer Completion**: It indicates whether a playback buffer has been emptied or a recording buffer has been filled.
- **Error Reporting**:
- Underrun (Playback): Occurs when the device consumes data faster than the stream handler provides it. Under OS/2 Warp, if you want the stream handler to pause the device upon underrun, report both the `ERROR_DEVICE_UNDERRUN` status and the `SHD_WRITE_COMPLETE` flag.
- Overrun (Recording): Occurs when the device generates data faster than the stream handler provides empty buffers. This often results in data loss as there is no storage available for the incoming digital stream.
- **Buffer Discipline**: The VSD/PDD must return buffers in the exact order they were received and must not hold onto them. Failing to return buffers promptly can cause application hangs.
Example Code
The following code illustrates a Physical Device Driver reporting that a read (recording) operation has completed for a specific buffer.
#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 */
/* ... Assume handles and buffer pointers are valid ... */
/*----------------------------------------------------------------------*/
/* Report that a read (record) buffer has been filled by the PDD. */
/*----------------------------------------------------------------------*/
shdpb.ulFunction = SHD_REPORT_INT;
shdpb.hstream = hstream;
shdpb.pBuffer = pBuffer;
shdpb.ulFlag = SHD_READ_COMPLETE;
shdpb.ulStatus = LengthRecordedBuffer; /* Actual bytes recorded */
shdpb.ulStreamTime = ulStreamTime;
ulRC = pshdfn(&shdpb);
if (ulRC) {
return (ulRC); /* error! */
}