Like other installable drivers, client-applications must open a video capture device before using it and close it when finished using it, so the device will be available to other applications. When a driver receives an open request, it returns a value that the system will use for dwDriverID sent with subsequent messages. When your device driver receives other messages, it can use this value to identify instance data needed for operation. Drivers can use the instance data for information related to the client that opened a device.
It's up to you to decide if your device driver will support more than one client simultaneously. If you do this, though, remember to check the dwDriverID parameter to determine which channel is being accessed.
For DRV_OPEN, the lParam2 parameter contains a pointer to a VIDEO_OPEN_PARMS data structure containing information about the open. This structure has the following members:
typedef struct {
DWORD dwSize; // Specifies the structure size
FOURCC fccType; // Contains 'vcap'
FOURCC fccComp; // Reserved; do not use
DWORD dwVersion; // Command set version
DWORD dwFlags; // Type of channel being opened
DWORD dwError; // Error to return if open fails
LPVOID pV1Reserved; // Reserved; do not use
LPVOID pV2Reserved; // Reserved; do not use
DWORD dwDevNode; // Registry device not for PNP devices
} VIDEO_OPEN_PARMS;
The fccType member of this structure will contain the four character code 'vcap'. Because of the four video capture channels, video capture drivers must examine the flags set in the dwFlags member of the VIDEO_OPEN_PARMS data structure to determine the type of channel being opened. Your driver should be prepared to open (and conversely, close) the video channels in any order.
The following flags are defined for the video channels:
| Channel | Description |
|---|---|
| VIDEO_EXTERNALIN | An external input channel responsible for loading images into the frame buffer. |
| VIDEO_EXTERNALOUT | An external output channel responsible for displaying images in the frame buffer to an external or system monitor, or to an overlay device. |
| VIDEO_IN | A video input channel responsible for transferring images from the frame buffer to system memory. This might include a translation step or reformatting of the image. For example, reformatting a 16-bit RGB image to an 8 bit palette image. |
| VIDEO_OUT | A video output channel responsible for transferring images into the frame buffer from the CPU. (The sample driver does not use this channel type.) |
The dwVersion member specifies the version of the video capture command set used by MSVIDEO.DLL. The version number lets your driver identify the command set to determine its capabilities. For the initial release of the video capture command set, your driver does not have to detect and adjust itself for multiple versions of the command set. Future versions of your driver can use this value to enable new features that depend on new capabilities of the video capture command set.
The dwError member specifies an error value the driver might return to the client-application if it fails the open.
The dwDevNode member specifies the Device Node for plug and play compatible drivers. For non-Plug and Play devices, this member will be NULL.