DDCMD_DEREG_STREAM
The DDCMD_DEREG_STREAM message removes a stream instance from a device driver. The stream handler directs the Physical Device Driver (PDD) or Vendor Specific Driver (VSD) to deregister the stream, effectively destroying the stream instance and all associated data.
Syntax
#include <os2.h> rc = DDCMDEntryPoint(pParmIn);
Parameters
- pParmIn (PDDCMDDEREGISTER) - input
- A pointer to a DDCMDDEREGISTER data structure which contains the handle of the stream to be destroyed.
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.
- FAILURE: Device-driver-specific error.
Remarks
This message severs the communication link between the PDD and the stream handler for a specific stream instance.
- **Buffer Management**: Upon deregistration, the VSD/PDD loses access to any buffers associated with the stream. These buffers are returned to the Sync Stream Manager (SSM) by the stream handler.
- **Synchronization**: The VSD/PDD must not return from this call until it has completely ceased using all buffers associated with the stream.
- **Cleanup**: The device driver is responsible for cleaning up all internal resources allocated for the specified stream handle.
Example Code
The following code illustrates a stream handler requesting a stream to be deregistered from the physical device driver.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
DDCMDDEREGISTER ddcmdpb; /* Parameter block */
PDDCMDFN pddcmdfn; /* Pointer to DDCMD entry point */
/* ... Assume hstream and pddcmdfn are valid ... */
/*-------------------------------------------------------------------*/
/* The stream handler deregisters with the physical device driver. */
/*-------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_DEREG_STREAM;
ddcmdpb.hstream = hstream;
ulRC = pddcmdfn(&ddcmdpb);
if (ulRC) {
return (ulRC); /* error! */
}