DDCMD_WRITE
The DDCMD_WRITE message performs a write operation from a buffer to a physical device. It is used by a stream handler to pass a "full" buffer of data to the Physical Device Driver (PDD) for output.
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 data buffer, and the size of the data to be written.
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 primary mechanism for a stream handler to deliver data to a PDD (e.g., during audio playback).
- **Buffer Passing**: The stream handler provides a buffer containing data to the PDD.
- **Addressing**: The pBuffer pointer type is determined during stream registration via DDCMD_REG_STREAM. It can be a physical 0:32 pointer, a 16:16 far pointer, or a global linear pointer.
- **Zero-Length Buffers**: If the driver receives a 0-length buffer, it should not reject it. The driver should perform no action and return the buffer in the same sequence in which it was received.
Example Code
The following code illustrates how a stream handler performs a write of 32KB of data to the physical device driver.
#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 write to the physical device driver. */
/*--------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_WRITE;
ddcmdpb.hstream = hstream;
ddcmdpb.pBuffer = pBuffer;
ddcmdpb.ulBufferSize = 32768;
ulRC = pddcmdfn(&ddcmdpb);
if (ulRC) {
return (ulRC); /* error! */
}