DDCMD_READ
The DDCMD_READ message performs a read operation from a physical device into a buffer. This message is primarily used by a stream handler to provide an empty buffer to the Physical Device Driver (PDD) to be filled with data (e.g., during audio recording or data capture).
Syntax
#include <os2.h> rc = DDCMDEntryPoint(pParmIn);
Parameters
- pParmIn (PDDCMDREADWRITE) - input
- A pointer to a DDCMDREADWRITE data structure. This structure contains the stream handle, the pointer to the buffer to be filled, and the size of the buffer.
Return Value
- rc (ULONG) - returns
- Error code indicating success or the type of failure:
- NO_ERROR: Success.
- ERROR_INVALID_FUNCTION: Illegal function requested.
- ERROR_INVALID_STREAM: Invalid stream handle.
- ERROR_INVALID_BLOCK: Invalid address passed in the parameter block.
- FAILURE: Device-driver-specific error return code.
Remarks
This message is the standard mechanism for a stream handler to pass "empty" work units to a PDD.
- **Buffer Filling**: The PDD is responsible for filling the provided pBuffer with data from the hardware.
- **Addressing**: The pBuffer pointer type (physical 0:32, 16:16 far, or global linear) is determined during stream registration via DDCMD_REG_STREAM.
- **Zero-Length Buffers**: If the PDD receives a buffer with ulBufferSize set to 0, it must not reject it. Instead, the driver should perform no action on the buffer and return it in the same relative order it was received.
Example Code
The following code illustrates a stream handler providing a 32KB empty buffer to the PDD for a read operation.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
DDCMDREADWRITE ddcmdpb; /* Parameter block */
PDDCMDFN pddcmdfn; /* Pointer to DDCMD entry point */
PVOID pBuffer; /* Pointer to buffer */
/* ... Assume hstream, pddcmdfn, and pBuffer are initialized ... */
/*-------------------------------------------------------------------*/
/* Perform a read from the physical device driver. */
/*-------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_READ;
ddcmdpb.hstream = hstream;
ddcmdpb.pBuffer = pBuffer;
ddcmdpb.ulBufferSize = 32768;
ulRC = pddcmdfn(&ddcmdpb);
if (ulRC) {
return (ulRC); /* error! */
}