ActivateDeviceEx (Windows Embedded CE 6.0)
1/6/2010
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 CE 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. Both of these functions replace the RegisterDevice function.
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.** For Windows Embedded CE, for more information on BusEnum.dll, see Bus Enumerator.**
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_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_TRUSTEDCALLERONLY |
0x00010000 |
Driver can only be opened by a privileged application. |
The dwClientInfo parameter of ActivateDevice is a registry entry for the DEVLOAD_CLIENTINFO_VALNAME value.
Requirements
| Header | winbase.h |
| Library | coredll.lib |
| Windows Embedded CE | Windows CE .NET 4.0 and later |
See Also
Reference
Device Manager Functions
DeactivateDevice
REGINI
XXX_Init (Device Manager)
Concepts
Bus Enumerator
Device Interface Notifications
Device Manager Security