VC_InstallDriver

LRESULT
VC_InstallDriver(
    PVC_PROFILE_INFO pProfile,
    PPROFILE_CALLBACK pCallback,
    PVOID pContext
    );

The VC_InstallDriver function installs a kernel-mode driver and allows modification of configuration parameters.

Parameters
pProfile
Address of a VC_PROFILE_INFO structure returned by VC_OpenProfileAccess, containing the kernel-mode driver’s name.
pCallback
Pointer to a driver-supplied function that is called before the kernel-mode driver is reloaded. Can be NULL.

The function should return TRUE if the installation should continue, or FALSE if the installation should be terminated. It uses the following prototype definition: 

BOOL pCallback (PVOID pContext);
pContext
Pointer to a driver-defined structure that is passed as input to the function pointed to by pCallback. Can be NULL.
Return Value

Returns one the following values.

Value

Definition

DRVCNF_OK

The driver is correctly loaded and started. System restart is not required.

DRVCNF_CANCEL

An error occurred.

Comments

Under Windows NT, kernel-mode drivers are considered to be services under the control of the Service Control Manager. The VC_InstallDriver function establishes a kernel-mode driver as a service by performing the following operations, in order:

  1. Calling OpenSCManager to create a connection to the local Service Control Manager. OpenSCManager is called with a desired access type of SC_MANAGER_ALL_ACCESS, which requires Administrators privilege. (OpenSCManager is described in the Win32 SDK.)

  2. Calling CreateService to create a kernel-mode driver service and obtain a service handle. The function sets the service’s start type to SERVICE_DEMAND_START, so it will not automatically reload when the system is restarted. (CreateService is described in the Win32 SDK.)

  3. Unloading the kernel-mode driver, if it is loaded.

  4. Calling the driver-supplied function specified by the pCallback parameter. Generally, drivers use this function to modify configuration parameters in the registry, using VC_WriteProfile.

  5. Reloading and restarting the kernel-mode driver, setting its start type to SERVICE_SYSTEM_START, so it will automatically reload and restart when the system is restarted.

A result of calling CreateService is the creation of a driver subkey under the \Services registry key. The path to the subkey is HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\DriverName, where DriverName is the driver name specified as input to VC_OpenProfileAccess.

Typically, a user-mode video capture driver calls VC_InstallDriver when its DriverProc function receives a DRV_CONFIGURE message.