NdisIMInitializeDeviceInstanceEx

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

NdisIMInitializeDeviceInstanceExcalls an NDIS intermediate driver's MiniportInitializefunction 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
DeviceContextOPTIONAL 
);

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\Servicesregistry 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

NdisIMInitializeDeviceInstanceExcan return either of the following:

NDIS_STATUS_SUCCESS

The intermediate driver's virtual network adapter was successfully initialized.

NDIS_STATUS_NOT_ACCEPTED

NdisIMInitializeDeviceInstanceExfailed because the device specified by DriverHandlehas already been initialized.

Comments

An NDIS intermediate driver should call NdisIMInitializeDeviceInstanceExfrom its ProtocolBindAdapterfunction, thereby controlling when NDIS calls the driver's MiniportInitializefunction to set up the driver's virtual network adapter. A failure to call NdisIMInitializeDeviceInstanceExor NdisIMInitializeDeviceInstancefrom 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 MiniportInitializefunction runs.

Before it calls NdisIMInitializeDeviceInstanceEx, the intermediate driver's ProtocolBindAdapterfunction must make a successful call to NdisOpenAdapter, thereby binding the intermediate driver as a protocol to the underlying network adapter miniport. The ProtocolBindAdapterfunction can allocate an area at DeviceContextas 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 MiniportInitializefunction 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 NdisIMInitializeDeviceInstanceExcauses NDIS to call the intermediate driver's MiniportInitializefunction. MiniportInitializeallocates 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 MiniportInitializefunction can call NdisIMGetDeviceContextto gain access to the area at DeviceContextif such an area is provided by its ProtocolBindAdapterfunction.

After MiniportInitializereturns 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

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	3.0 and later	Ndis.h		Ndislib.lib

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.