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.

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

Requirements

See Also

Reference

Device Manager Functions
DeactivateDevice
REGINI
XXX_Init (Device Manager)

Concepts

Bus Enumerator
Device Interface Notifications
Device Manager Security

Other Resources

Hive-Based Registry