Share via

XXX_Init (Device Manager)

  • Article

Other versions of this page are also available for the following:

Windows Mobile Not SupportedWindows Embedded CE Supported

8/28/2008

This function initializes a device.

Syntax

DWORD XXX_Init(
  LPCTSTR pContext,
  DWORD dwBusContext
);

Parameters

  • pContext
    [in] Pointer to a string containing the registry path to the active key for the stream interface driver.
  • lpvBusContext
    [in] Potentially process-mapped pointer passed as the fourth parameter to ActivateDeviceEx. If this driver was loaded through legacy mechanisms, then dwBusContext is zero. This pointer, if used, has only been mapped again as it passes through the protected server library (PSL). The XXX_Init function is responsible for performing all protection checking. **

Return Value

Returns a handle to the device context created if successful. Returns zero if not successful. This handle is passed to the XXX_Open (Device Manager), XXX_PowerDown (Device Manager), XXX_PowerUp (Device Manager), and XXX_Deinit (Device Manager) functions.

Remarks

Device Manager calls this function as a result of a call to the ActivateDeviceEx function. When the user starts using a device, such as inserting a PC Card, Device Manager calls this function to initialize the device. Applications do not call this function.

If your stream interface supports multiple instances of the same type of device file name, you only need to expect one call to the XXX_Init function for each instance of the device file name. The XXX_Init function returns a separate handle each time it executes. An example is the sample serial port driver, located in %_WINCEROOT%\Public\Common\Oak\Drivers\Serial. It supports multiple COMx: device file names. Stream interfaces that only support one instance of a device file name can return any non-zero value.

Device Manager specifies a pointer to a string containing the registry path to the active key of the specific PC Card device in the pContext parameter. Usually, the string contains the registry path to a numbered subkey of the HKEY_LOCAL_MACHINE\Drivers\Active registry key. Your initialization function uses this information to access data stored in the registry.

The following list shows the tasks this function can perform:

  • Initialize the installed device to a default state.
  • Allocate resources used globally by the device driver.
  • Register a status callback function with PC Card Services.
    When the status of the device changes, the operating system calls this status callback function. For example, the status of a PC Card changes when you insert it or remove it.
  • Map system memory and I/O space to a PC Card device memory and I/O space.
  • Request notification on specific callback events.
  • Register an interrupt callback function for an interrupt-driven device.
    When the device generates an interrupt, the operating system calls this interrupt callback function.

Note

API ready notifications should not be set in the XXX_Init routine. Instead a driver should use the PostInit and BusPostInit IOCTLs to set API ready notifications. API ready notifications can be set in the XXXIOControl routine after the XXXInit routine completes. This implementation ensures that other drivers will not encounter a failure if a context switch occurs after the XXX_Init designates an API as ready, but before the call completes and a device handle is returned to the device manager.

The following example shows the registry keys to define so that PostInit and BusPostInit calls will occur.

#define DEVLOAD_INITCODE_VALNAME TEXT("Ioctl") //Device IO control code to indicate context
#define DEVLOAD_INITCODE_VALTYPE REG_DWORD
#define DEVLOAD_BUSINITCODE_VALNAME TEXT("BusIoctl") //Bus IO control code to indicate context
#define DEVLOAD_BUSINITCODE_VALTYPE REG_DWORD

The following outline illustrates the actual procedure to follow when using PostInit and BusPostInit.

Load Order 0

Driver1 -> Init()

Driver1 -> IOControl(Ioctl)

Driver2 -> Init()

Driver2 -> IOControl(BusIoctl)

Load Order 1

Driver3 -> Init()

Driver3 -> IOControl(Ioctl)

Driver4 -> Init()

Driver4 -> IOControl(Ioctl)

Device Manager uses the XXX prefix. When implementing the stream interface, replace XXX with a prefix appropriate for your specific implementation or use undecorated entry point names in conjunction with DEVFLAGS_NAKEDENTRIES. For more information about other valid Flags values, see ActivateDeviceEx.

Requirements

Header Developer Implemented
Library Developer Implemented
Windows Embedded CE Windows CE 1.0 and later

See Also

Reference

ActivateDeviceEx
XXX_Deinit (Device Manager)
XXX_IOControl (Device Manager)
XXX_Open (Device Manager)
XXX_PowerDown (Device Manager)
XXX_PowerUp (Device Manager)

Concepts

Device File Names