ActivateDeviceEx (Compact 2013)

3/26/2014

This function loads a driver and adds its registry values to the Active key in the registry.

Syntax

HANDLE ActivateDeviceEx(
  LPCWSTR lpszDevKey, 
  LPCVOID lpRegEnts, 
  DWORD cRegEnts, 
  LPVOID lpvParam
);

Parameters

• lpszDevKey
  [in] Pointer to a string containing the registry path of the device driver's registry key. This key contains the driver's DLL name, prefix, and other data. For information about the subkeys of the HKEY_LOCAL_MACHINE\Drivers\Active registry key, see Device Manager Registry Keys.

• lpRegEnts
  [in] Pointer to an array of REGINI structures, each of which defines a registry value to add to the device's Active registry key before its driver is loaded. Set to NULL unless it is for a bus driver.

• cRegEnts
  [in] Count of the number of REGINI structures to which lpRegEnts points. This affects a generalization of the ActivateDevice function.

• lpvParam
  [in] Opaque pointer to a driver-specific data structure. You can use it to pass parameters to the loaded driver without having to write them through the registry.

  lpvParam can be used by bus drivers to pass bus-specific information, entry points, or both to loaded drivers. Using this parameter prevents clients of that bus from becoming bus-agnostic. This is acceptable for some buses, especially those whose drivers cannot become bus-agnostic.

  lpvParam is passed to the XXX_Init (Device Manager) function as a second parameter.

Return Value

Returns a handle that you can use later as the parameter to the DeactivateDevice function, if successful. If the function is not successful, it returns NULL. To obtain extended error information, call GetLastError.

Remarks

Loading a device with ActivateDeviceEx allows a device to read its activation handle from its Active registry key. In versions of Windows Embedded Compact prior to Windows CE 5.0, the Active registry key value was not written to the registry until the driver's Init entry point completed.

ActivateDeviceEx offers more functionality than ActivateDevice.

ActivateDeviceEx can load non-stream drivers, protocols, and services that are bound to the Device Manager. It can also load multiple drivers with Bus Enumerator (BusEnum.dll) and can add bus-specific values to the Active key.

ActivateDeviceEx reads the registry key specified in lpszDevKey to get the DLL name, device prefix, index, and other values. Next, it adds the device to the active device list, and stores the relevant values in the active device list. If there is no device index specified in the key named in lpszDevKey, it then assigns a free index. Finally, it loads the device driver DLL in the process space of the Device Manager.

ActivateDeviceEx can return zero for success rather than failure. If either DEVFLAGS_NOLOAD or DEVFLAGS_UNLOAD is set in the Flags value of the device key, ActivateDeviceEx returns zero. In this case, there is no way to tell the difference between success and failure.

The Index value indicates port numbering with stream interface drivers, such as COM0: or COM1:. If there is no Index value, the Device Manager generates one.

The Flags value is a set of bits that modify the behavior of ActivateDeviceEx. This value is optional and is set to zero, if there is no value present. Bits 3 through 23 are reserved and must be set to zero. The driver being loaded can use bits 24 through 31 of the Flags value. The following table shows the defined bits, which are defined in %_WINCEROOT%\Public\Common\DDK\Inc\Devload.h.

Flag	Value	Description
DEVFLAGS_NONE	0x00000000	No flags are defined.
DEVFLAGS_UNLOAD	0x00000001	Driver unloads after a call to the XXX_Init entry point or after the XXX_Init entry point returns. No error code is returned. Bus Enumerator typically runs with this flag.
DEVFLAGS_LOADLIBRARY	0x00000002	Driver is loaded with LoadLibrary instead of LoadDriver.
DEVFLAGS_NOLOAD	0x00000004	Driver is not loaded.
DEVFLAGS_NAKEDENTRIES	0x00000008	Driver entry points do not have a XXXPrefix prepended.
DEVFLAGS_LOAD_AS_USERPROC	0x00000010	Driver is loaded to the user mode processor.
DEVFLAGS_BOOTPHASE_1	0x00001000	Driver is loaded during boot phase one. By default, device drivers are loaded during boot phase two. Boot phase zero is before the Device Manager loads. Boot phase one is to find the registry. Boot phase two is when initial device drivers load. Boot phase three is after initial device drivers load.
DEVFLAGS_IRQ_EXCLUSIVE	0x00000100	Driver loads only when it has exclusive access to the IRQ.
DEVFLAGS_LOADDISABLED	0x00020000	Driver is not enabled automatically when loaded.
DEVFLAGS_LOADINOWNGROUP	0x00040000	Driver is loaded into a new and separate ProcGroup.

The dwClientInfo parameter of ActivateDevice is a registry entry for the DEVLOAD_CLIENTINFO_VALNAME value.

Requirements

Header	winbase.h
Library	coredll.lib

See Also

Reference

Device Manager Functions
DeactivateDevice
REGINI
XXX_Init (Device Manager)