VCUSER_HANDLE
VC_OpenDevice(
PWCHAR pDeviceName,
int DeviceIndex
);
The VC_OpenDevice function opens a specified video capture device.
Parameters
pDeviceName
Pointer to a UNICODE string containing the name of the device to open. If NULL, DeviceIndex specifies the device.
DeviceIndex
Index number used to identify the device, if pDriverName is NULL. If pDriverName points to a string, DeviceIndex must be zero (see the following Comments section).
Return Value
Returns a handle to the kernel-mode driver, if the operation succeeds. Otherwise returns NULL.
Comments
A user-mode driver should call VC_OpenDevice when it receives a DRV_OPEN message. Typically, the driver receives multiple DRV_OPEN messages, because DRV_OPEN is sent each time the client opens one of the video channels (VIDEO_EXTERNALIN, VIDEO_IN, VIDEO_OUT, or VIDEO_EXTERNALOUT). The driver only needs to call VC_OpenDevice for the client’s first DRV_OPEN message, as illustrated by the sample video capture drivers.
If pDeviceName points to a string, that string is used as the device name. Because the current implementation does not allow a single kernel-mode video capture driver to support more than one device, a device number is not appended to this string. The DeviceIndex value must be zero. The pDriverName value must be a pointer to the same string that was specified as input to VC_OpenProfileAccess.
If pDeviceName is NULL, then the DeviceIndex parameter specifies an index value. This value is appended to the device name “vidcap”, which is defined by DD_VIDCAP_DEVICE_NAME_U in ntddvidc.h. For kernel-mode drivers using VCKernel.lib, this name is used by VC_Init when creating a device object. Thus, specifying a DeviceIndex value allows a user-mode driver to attempt to open a video capture device without specifying a particular device name, such as “bravado”. See the sample msyuv.dll driver for an example of using the DeviceIndex parameter. (For more information about device objects, see the Kernel-Mode Drivers Design Guide.)
The VC_OpenDevice function calls CreateFile, described in the Win32 SDK, to open the device. As a result of this call, the kernel-mode driver receives an IRP_MJ_CREATE function code. When a kernel-mode driver using VCKernel.lib receives this function code, its DeviceOpenFunc function is called.