DDCMD_SETUP
The DDCMD_SETUP message performs device-specific stream instance setup. It is primarily used to notify the Physical Device Driver (PDD) that a specific stream instance is becoming active and to synchronize state before streaming begins.
Syntax
#include <os2.h> rc = DDCMDEntryPoint(pParmIn);
Parameters
- pParmIn (PDDCMDSETUP) - input
- A pointer to a DDCMDSETUP data structure. The pSetupParm and ulSetupParmSize fields within this structure refer to a SETUP_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.
- ERROR_INVALID_STREAM: Invalid stream handle.
- ERROR_INVALID_REQUEST: Invalid setup request.
- ERROR_STREAM_NOT_STOP: The stream must be in a stopped state to perform this function.
- FAILURE: Device-driver-specific error return code.
Remarks
This message indicates to the physical device driver that a specific stream instance will become the active stream instance (performing a "context switch" if necessary).
The pSetupParm field is used for device-specific information. A common use case is to pass the current stream time from the stream handler to the PDD. This is necessary if a seek operation was requested before the stream started; the PDD uses this millisecond value to adjust its internal hardware reference time to the new position.
Example Code
The following code illustrates how a stream handler performs setup to synchronize the stream time within the physical device driver.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
DDCMDSETUP ddcmdpb; /* Parameter block */
PDDCMDFN pddcmdfn; /* Pointer to DDCMD entry point*/
ULONG ulStreamTime; /* Stream time */
/* ... Assume hstream, pddcmdfn, and ulStreamTime are initialized ... */
/*------------------------------------------------------------------*/
/* Activate a stream instance in a physical device driver (Switch */
/* context) and set the initial stream time reference. */
/*------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_SETUP;
ddcmdpb.hstream = hstream;
ddcmdpb.pSetupParm = &ulStreamTime; /* Passing current time */
ddcmdpb.ulSetupParmSize = sizeof(ulStreamTime);
ulRC = pddcmdfn(&ddcmdpb);
if (ulRC) {
return (ulRC); /* error! */
}