NdisIMInitializeDeviceInstanceEx function (ndis.h)

Article
04/18/2022

The NdisIMInitializeDeviceInstanceEx function initiates the initialization operation for a virtual miniport and optionally sets up state information about the virtual miniport for subsequently bound protocol drivers.

Syntax

NDIS_STATUS NdisIMInitializeDeviceInstanceEx(
  [in]           NDIS_HANDLE  DriverHandle,
  [in]           PNDIS_STRING DriverInstance,
  [in, optional] NDIS_HANDLE  DeviceContext
);

Parameters

[in] DriverHandle

The miniport driver handle that the NdisMRegisterMiniportDriver function returns at NdisMiniportDriverHandle .

[in] DriverInstance

A pointer to an NDIS_STRING type that describes a caller-initialized counted string in the system-default character set. The string contains the name of the registry key in which the driver stores information about a virtual miniport and, possibly, binding-specific information. For Microsoft 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.

[in, optional] DeviceContext

A pointer to caller-supplied memory to be set up with driver-defined device context information about the virtual miniport, which still higher level protocol drivers that subsequently bind themselves to this virtual miniport 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:

Return code	Description
NDIS_STATUS_SUCCESS	NDIS initiated the initialization operation for the intermediate driver's virtual miniport.
NDIS_STATUS_NOT_ACCEPTED	NdisIMInitializeDeviceInstanceEx failed because the device specified by DriverHandle has already been initialized.

Remarks

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

Before it calls NdisIMInitializeDeviceInstanceEx, the intermediate driver's ProtocolBindAdapterEx function should bind to any underlying miniport drivers that are required for the intermediate driver to function. The ProtocolBindAdapterEx function can allocate an area at DeviceContext as well, possibly setting it up with intermediate driver-determined information about the capabilities of the underlying miniport adapter and that was collected by ProtocolBindAdapterEx. The intermediate driver's MiniportInitializeEx function might use such information subsequently to set up this context area with information about the driver's virtual miniport.

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

The call to MiniportInitializeEx can happen at a later time and therefore is not necessarily within the context of the call to NdisIMInitializeDeviceInstanceEx. If NDIS never calls MiniportInitializeEx for the virtual miniport that is referenced in a call to NdisIMInitializeDeviceInstanceEx and the intermediate driver no longer requires the virtual miniport, the intermediate driver should call the NdisIMCancelInitializeDeviceInstance function 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 adapter. If that binding is removed before NDIS calls MiniportInitializeEx, the intermediate driver should call NdisIMCancelInitializeDeviceInstance to cancel the initialization of the virtual miniport.

MiniportInitializeEx allocates any resources that the driver requires to carry out network I/O operations, such as calling the NdisMSetMiniportAttributes function, and to initialize the driver's virtual miniport to an operational state. Then, higher-level protocol drivers can bind themselves to its virtual miniport when the intermediate driver's initialization is completed successfully.

After MiniportInitializeEx returns control, the intermediate driver's device context area, if any, can contain any intermediate-driver-defined data that subsequently enables all higher-level protocol drivers that are bound to the same virtual miniport to access information in that context area. Such a higher-level protocol driver can query the intermediate-driver-supplied device context with the NdisIMGetBindingContext function.

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

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

Requirements

Requirement	Value
Minimum supported client	Supported for NDIS 6.0 and NDIS 5.1 drivers (see NdisIMInitializeDeviceInstanceEx (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see NdisIMInitializeDeviceInstanceEx (NDIS 5.1)) in Windows XP.
Target Platform	Desktop
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL
DDI compliance rules	Irql_IM_Function(ndis)