DDCMD_REG_STREAM
The DDCMD_REG_STREAM message registers a stream instance with a device driver for the first time. It establishes the communication link between the stream handler and the Physical Device Driver (PDD).
Syntax
#include <os2.h> rc = DDCMDEntryPoint(pParmIn);
Parameters
- pParmIn (PDDCMDREGISTER) - input
- A pointer to a DDCMDREGISTER data structure.
- Valid values for ulStreamOperation include:
- STREAM_OPERATION_CONSUME: The device consumes data (e.g., playback).
- STREAM_OPERATION_PRODUCE: The device produces data (e.g., recording).
- Valid values for ulAddressType include:
- ADDRESS_TYPE_VIRTUAL: 16:16 far pointer.
- ADDRESS_TYPE_PHYSICAL: 0:32 physical address.
- ADDRESS_TYPE_LINEAR: 0:32 global linear address.
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_HNDLR_REGISTERED: Stream had already been registered with the Sync/Stream Manager.
- ERROR_INVALID_SPCBKEY: Invalid SPCBKEY.
- ERROR_INITIALIZATION: An error occurred during device initialization.
- ERROR_STREAM_CREATION: An error occurred during the creation of this stream instance.
- FAILURE: Device-driver-specific error return code.
Remarks
A stream handler must register its entry point (via the pSHDEntryPoint field) with the device driver exactly once for each stream instance. This registration is critical as it provides the PDD with the callback address necessary to notify the stream handler of events or buffer completions.
Example Code
The following code illustrates how to register a stream instance as a "consumer" (playback) with a physical device driver.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
DDCMDREGISTER ddcmdpb; /* Parameter block */
PDDCMDFN pddcmdfn; /* Pointer to DDCMD entry point */
ULONG ulSysFileNum; /* Global file handle */
PSHDFN pshdfn; /* Pointer to SHD entry point */
SPCBKEY spcbkey; /* Stream protocol key */
/*-------------------------------------------------------------------*/
/* Register a stream instance with a physical device driver. */
/*-------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_REGISTER;
ddcmdpb.hstream = hstream;
ddcmdpb.ulSysFileNum = ulSysFileNum;
ddcmdpb.pSHDEntryPoint = pshdfn;
ddcmdpb.ulStreamOperation = STREAM_OPERATION_CONSUME;
ddcmdpb.spcbkey = spcbkey;
ulRC = pddcmdfn (&ddcmdpb);
if (ulRC) {
return (ulRC); /* error! */
}