DDCMD_CONTROL
The DDCMD_CONTROL message performs a device-specific command, allowing a stream handler to control the immediate actions of a Physical Device Driver (PDD).
Syntax
#include <os2.h> rc = DDCMDEntryPoint(pParmIn);
Parameters
- pParmIn (PDDCMDCONTROL) - input
- A pointer to a DDCMDCONTROL data structure. The pParm and ulParmSize fields within this structure refer to the CONTROL_PARM data structure. Valid values for the ulCmd field include:
- DDCMD_START: Start a device.
- DDCMD_STOP: Stop a device and return the current position.
- DDCMD_PAUSE: Pause a device and return the current position.
- DDCMD_RESUME: Resume a paused device.
- DDCMD_ENABLE_EVENT: Enable event detection in the device driver.
- DDCMD_DISABLE_EVENT: Disable event detection in the device driver.
- DDCMD_PAUSE_TIME: Pause stream time without pausing the physical stream.
- DDCMD_RESUME_TIME: Resume stream time.
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_REQUEST: Device driver does not support events (returned for DDCMD_ENABLE_EVENT).
- ERROR_INVALID_STREAM: Invalid stream handle.
- ERROR_INVALID_SEQUENCE: Invalid device control command sequence.
- ERROR_INSUFF_BUFFER: The device driver lacks buffers to perform the requested action.
- ERROR_STREAM_NOT_STARTED: The action requires the stream to be in a started state.
- ERROR_TOO_MANY_EVENTS: Attempted to enable more events than the driver supports.
- FAILURE: Device-driver-specific error return code.
Remarks
The stream handler uses this command to manage transport states (play, stop, pause) and event notification settings within the PDD. It is the primary mechanism for synchronizing physical hardware state with the logical stream state.
Example Code
The following code illustrates a stream handler requesting the PDD to stop its current task (for example, stopping audio playback).
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
DDCMDCONTROL ddcmdpb; /* Parameter block */
PDDCMDFN pddcmdfn; /* Pointer to DDCMD entry point */
/* ... Assume hstream and pddcmdfn are valid ... */
/*-------------------------------------------------------------------*/
/* The stream handler directs the physical device driver to stop. */
/*-------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_CONTROL;
ddcmdpb.hstream = hstream;
ddcmdpb.pParm = NULL;
ddcmdpb.ulParmSize = 0;
ddcmdpb.ulCmd = DDCMD_STOP;
ulRC = pddcmdfn(&ddcmdpb);
if (ulRC) {
return (ulRC); /* error! */
}