NdisIMInitializeDeviceInstanceEx (NDIS 5.1) function

Note   NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

An NDIS intermediate driver calls the NdisIMInitializeDeviceInstanceEx function to initiate the initialization operation for a virtual NIC and optionally to set up state information about the virtual NIC for subsequently bound protocols drivers.

Syntax

NDIS_STATUS NdisIMInitializeDeviceInstanceEx(
  _In_     NDIS_HANDLE  DriverHandle,
  _In_     PNDIS_STRING DriverInstance,
  _In_opt_ NDIS_HANDLE  DeviceContext
);

Parameters

• DriverHandle [in]
  Specifies the handle returned by NdisIMRegisterLayeredMiniport.

• DriverInstance [in]
  Pointer to an NDIS_STRING type that describes a caller-initialized counted string, in the system-default character set, naming the registry key in which the driver stores information about its virtual NIC and, possibly, binding-specific information. For Windows 2000 and later drivers, this string contains Unicode characters. That is, for Windows 2000 and later, NDIS defines the NDIS_STRING type as a UNICODE_STRING type.

• DeviceContext [in, optional]
  Pointer to caller-supplied memory to be set up with driver-defined device context information about the virtual NIC, which still higher level protocol drivers that subsequently bind themselves to this virtual NIC can use. This parameter can be NULL if the intermediate driver has no such device context area.

Return value

NdisIMInitializeDeviceInstanceEx can return either of the following:

Remarks

An NDIS intermediate driver should call NdisIMInitializeDeviceInstanceEx from its ProtocolBindAdapter function. A failure to call NdisIMInitializeDeviceInstanceEx or NdisIMInitializeDeviceInstance from an NDIS intermediate driver effectively prevents that driver from loading successfully.

Before it calls NdisIMInitializeDeviceInstanceEx, the intermediate driver's ProtocolBindAdapter function should bind to any underlying miniport drivers that are required for the intermediate driver to function. 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 NIC, 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 NIC.

The intermediate driver's call to NdisIMInitializeDeviceInstanceEx causes NDIS to call the intermediate driver's MiniportInitialize function, if NDIS receives an IRP_MN_START_DEVICE to start the device. If NDIS does not receive such an IRP, NDIS will not call the intermediate driver's MiniportInitialize function.

The call to MiniportInitialize can happen at a later time and therefore is not necessarily within the context of the call to NdisIMInitialzieDeviceInstanceEx. If NDIS never calls MiniportInitialize for the virtual miniport that is referenced in a call to NdisIMInitialzieDeviceInstanceEx and the intermediate driver no longer requires the virtual miniport, the intermediate driver should call NdisIMCancelInitializeDeviceInstance to cancel the initialization of the virtual miniport. For example, suppose that an intermediate driver creates a virtual miniport in response to a successful binding to an underlying miniport. If that binding is removed before NDIS calls MiniportInitialize, the intermediate driver should call NdisIMCancelInitializeDeviceInstance to cancel the initialization of the miniport.

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 NIC to an operational state. Then, still higher level protocols can bind themselves to its virtual NIC 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 NIC to access information in that context area. Such a higher level protocol can query the intermediate-driver-supplied device context with NdisIMGetBindingContext.

Before NDIS calls an intermediate driver's MiniportInitialize function, the driver can call NdisIMCancelInitializeDeviceInstance to cancel the initialization operation.

After NDIS calls an intermediate driver's MiniportInitialize function, the driver must call NdisIMDeInitializeDeviceInstance to reverse the initialization operation.

Requirements

See also

ANSI_STRING

MiniportInitialize

NdisAllocateMemoryWithTag

NdisIMCancelInitializeDeviceInstance

NdisIMDeInitializeDeviceInstance

NdisIMGetBindingContext

NdisIMGetDeviceContext

NdisIMInitializeDeviceInstance

NdisIMRegisterLayeredMiniport

NdisInitializeString

NdisMSetAttributesEx

NdisOpenAdapter

ProtocolBindAdapter

UNICODE_STRING

Send comments about this topic to Microsoft