NdisIMInitializeDeviceInstanceEx

NdisIMInitializeDeviceInstanceEx calls an NDIS intermediate driver's MiniportInitialize function to initialize the driver's virtual network adapter and optionally to set up state information about the driver's virtual network adapter for subsequently bound protocols.

NDIS_STATUS
NdisIMInitializeDeviceInstanceEx(
IN NDIS_HANDLE DriverHandle,
IN PNDIS_STRING DriverInstance,
IN NDIS_HANDLE DeviceContext OPTIONAL );

Parameters

• DriverHandle
  Specifies the handle returned by NdisIMRegisterLayeredMiniport.

• DriverInstance
  Points to a buffered, caller-initialized counted string in the system-default character set, naming the registry key in which the driver stores information about its virtual network adapter and, possibly, binding-specific information.

  The intermediate driver's installation script created its key designated by DeviceInstance in the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services registry tree.

• DeviceContext
  Points to caller-supplied memory to be set up with driver-defined device context information about the virtual network adapter, which still higher level protocols that subsequently bind themselves to this virtual network adapter can use. This parameter can be NULL if the intermediate driver has no such device context area.

Return Values

NdisIMInitializeDeviceInstanceEx can return either of the following:

• NDIS_STATUS_SUCCESS
  The intermediate driver's virtual network adapter was successfully initialized.
• NDIS_STATUS_NOT_ACCEPTED
  NdisIMInitializeDeviceInstanceEx failed because the device specified by DriverHandle has already been initialized.

Comments

An NDIS intermediate driver should call NdisIMInitializeDeviceInstanceEx from its ProtocolBindAdapter function, thereby controlling when NDIS calls the driver's MiniportInitialize function to set up the driver's virtual network adapter. A failure to call NdisIMInitializeDeviceInstanceEx or NdisIMInitializeDeviceInstance from an NDIS intermediate driver effectively prevents that driver from loading itself successfully. Such a driver cannot make its virtual network adapter operational for still higher level protocols unless its MiniportInitialize function runs.

Before it calls NdisIMInitializeDeviceInstanceEx, the intermediate driver's ProtocolBindAdapter function must make a successful call to NdisOpenAdapter, thereby binding the intermediate driver as a protocol to the underlying network adapter miniport. The ProtocolBindAdapter function can allocate an area at DeviceContext as well, possibly setting it up with intermediate driver-determined information about the capabilities of the underlying network adapter, collected by ProtocolBindAdapter. The intermediate driver's MiniportInitialize function might use such information subsequently to set up this context area with information about the driver's virtual network adapter.

After its successful call to NdisOpenAdapter, the intermediate driver's subsequent call to NdisIMInitializeDeviceInstanceEx causes NDIS to call the intermediate driver's MiniportInitialize function. MiniportInitialize allocates any resources the driver needs to carry out network I/O operations, such as calling NdisMSetAttributesEx, and to initialize the driver's virtual network adapter to an operational state. Then, still higher level protocols can bind themselves to its virtual network adapter when the intermediate driver's initialization is completed successfully. The intermediate driver's MiniportInitialize function can call NdisIMGetDeviceContext to gain access to the area at DeviceContext if such an area is provided by its ProtocolBindAdapter function.

After MiniportInitialize returns control, the intermediate driver's device context area, if any, can contain any intermediate-driver-defined data that subsequently allows all higher level protocols bound to the same virtual network adapter to access information in that context area.

Requirements

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

MiniportInitialize, NdisIMDeInitializeDeviceInstanceEx, NdisIMGetDeviceContext, NdisIMInitializeDeviceInstance, NdisIMInitializeDeviceInstanceEx, NdisIMRegisterLayeredMiniport, NdisMSetAttributesEx, NdisOpenAdapter, ProtocolBindAdapter

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.