DDCMD_STATUS
The DDCMD_STATUS message requests status information from a physical device. It is used by a stream handler to query the current state or operational metrics of the Physical Device Driver (PDD).
Syntax
#include <os2.h> rc = DDCMDEntryPoint(pParmIn);
Parameters
- pParmIn (PDDCMDSTATUS) - input
- A pointer to a DDCMDSTATUS data structure. The pStatus and ulStatusSize fields within this structure refer to a STATUS_PARM data structure.
Return Value
- rc (ULONG) - returns
- Error code indicating success or the type of failure:
- NO_ERROR: Success.
- ERROR_INVALID_FUNCTION: Illegal function requested (the PDD may not support status queries).
- ERROR_INVALID_STREAM: Invalid stream handle.
- FAILURE: Device-driver-specific error return code.
Remarks
This message is the standard way to query a PDD. While support for this message may vary between drivers, its most common application is to retrieve the **current stream time**. When the stream handler needs to synchronize or report progress, it uses this message to get the high-precision time maintained by the hardware driver.
Example Code
The following code illustrates how a stream handler requests the current stream time from the physical device driver.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
DDCMDSTATUS ddcmdpb; /* Parameter block */
PDDCMDFN pddcmdfn; /* Pointer to DDCMD entry point */
/* ... Assume hstream and pddcmdfn are valid ... */
/*--------------------------------------------------------------------*/
/* Get the current stream time from the physical device driver. */
/*--------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_STATUS;
ddcmdpb.hstream = hstream;
ddcmdpb.pStatus = NULL; /* Return stream time */
ddcmdpb.ulStatusSize = 0;
ulRC = pddcmdfn(&ddcmdpb);
if (ulRC) {
return (ulRC); /* error! */
}