NdisIMInitializeDeviceInstanceEx (Windows Embedded CE 6.0)

1/6/2010

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

Syntax

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

Parameters

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

• DriverInstance
  [in] 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 NIC 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
  [in] Points to caller-supplied memory to be set up with driver-defined device context information about the virtual NIC, which still higher level protocols 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

The following table shows the return values for this function.

Remarks

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 NIC. 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 NIC 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 NIC 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 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.

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 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.

Requirements

See Also

Reference

NDIS Library Functions
MiniportInitialize
NdisAllocateMemory
NdisIMDeInitializeDeviceInstance
NdisIMGetBindingContext
NdisIMGetDeviceContext
NdisIMInitializeDeviceInstance
NdisIMRegisterLayeredMiniport
NdisInitializeString
NdisMSetAttributesEx
NdisOpenAdapter
ProtocolBindAdapter