NdisMSetMiniportSecondary 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.
NdisMSetMiniportSecondary sets the specified miniport driver adapter to the secondary role in relation to the primary miniport driver adapter. The primary miniport driver adapter handles all packet transfers and requests for information that are made by protocol drivers. However, NDIS can send specific requests to the secondary miniport driver adapter.
Note This function is intended to be used in NDIS 5.1 and earlier drivers and should not be used with later drivers.
Syntax
NDIS_STATUS NdisMSetMiniportSecondary(
_In_ NDIS_HANDLE MiniportAdapterHandle,
_In_ NDIS_HANDLE PrimaryMiniportAdapterHandle
);
Parameters
MiniportAdapterHandle [in]
Specifies the handle to the miniport driver adapter previously input to MiniportInitialize.PrimaryMiniportAdapterHandle [in]
Specifies the handle to the primary miniport driver adapter that has already been initialized with MiniportInitialize.
Return value
NdisMSetMiniportSecondary can return either of the following:
| Return code | Description |
|---|---|
| NDIS_STATUS_SUCCESS | The miniport driver adapter has been set to the secondary role in relation to the primary miniport driver adapter. The miniport driver can subsequently promote the secondary miniport driver adapter to the primary role. |
| NDIS_STATUS_FAILURE | An attempt to set the miniport driver adapter that is currently being initialized to the secondary role failed. |
Remarks
Protocol drivers can only bind to a miniport driver's primary adapter. All bindings to the miniport driver's secondary adapters are torn down.
A miniport driver can call NdisMSetMiniportSecondary during initialization of the secondary miniport driver adapter, that is from within the miniport driver's MiniportInitialize function. In this call, the miniport driver passes the handle to the miniport driver adapter being initialized in the MiniportAdapterHandle parameter and the handle to the primary miniport driver adapter that has already been initialized in the PrimaryMiniportAdapterHandle parameter. The primary miniport driver adapter handles all packet transfers and requests for information that are made by protocol drivers. However, NDIS can send specific requests to the secondary miniport driver adapter. For example, NDIS might query all miniport driver adapters for their media connectivity. The secondary miniport driver adapter must process and respond to this query.
After initialization of the secondary miniport driver adapter, the miniport driver can subsequently call the NdisMPromoteMiniport function to promote the secondary miniport driver adapter to the primary role.
Before the miniport driver calls NdisMSetMiniportSecondary, it must first determine if the miniport driver adapter being initialized is part of the miniport driver's bundle of miniport driver adapters. A miniport driver uses this bundle to balance the work load that each miniport driver adapter carries and to enable a secondary miniport driver adapter to take over packet transfers and information requests if the primary miniport driver adapter fails. This capability is called load balancing and failover (LBFO). For example, if the miniport driver's primary adapter fails, the miniport driver can call the NdisMRemoveMiniport function to remove the primary adapter from the system and from the miniport driver's bundle. The miniport driver can then call NdisMPromoteMiniport to promote a secondary adapter to the primary role.
To determine if the miniport driver adapter being initialized is part of the miniport driver's bundle, the miniport driver first calls the NdisOpenConfiguration function to obtain the handle for a registry key in which the miniport driver's configuration parameters are stored. Next, the miniport driver calls the NdisReadConfiguration function to retrieve the string value (REG_SZ) from the
BundleIndentifier
keyword under the miniport driver's registry key. The miniport driver should copy the string value to the miniport driver's internal structure in which the miniport driver stores information specific to the miniport driver adapter that is currently being initialized. This internal structure is also known as MiniportAdapterContext. The miniport driver's information (INF) file sets BundleIndentifier when the miniport driver is installed.
During initialization, the miniport driver should search through all miniport driver-adapter instances that the driver has already initialized to locate an instance that has an identical bundle-identifier value. To perform this search, the miniport driver inspects each instance's MiniportAdapterContext. If the driver locates a match, it should call NdisMSetMiniportSecondary and pass handles for both primary and secondary miniport driver adapters.
A miniport driver can call NdisMSetMiniportSecondary during the subsequent initialization of several miniport driver adapters to set them all to secondary roles. That is, multiple secondary miniport driver adapters can exist in a bundle. NDIS will only expose the miniport driver's primary adapter to transports. If transports request to send packets to the miniport driver or request to set or query information, NDIS will pass these requests to the miniport driver using the primary adapter. The miniport driver must provide LBFO for these requests as appropriate. The miniport driver only indicates up packets that were received from the network using the handle for the primary adapter.
Only miniport driver-adapter instances that are initialized by the same miniport driver and that belong to the miniport driver's bundle can call NdisMSetMiniportSecondary.
For information about adding LBFO capability to a miniport driver, see the readme for the passthru driver. This miniport driver is a sample intermediate miniport driver in the Microsoft Windows Driver Development Kit (DDK) and the Windows Driver Kit (WDK).
Requirements
Target platform |
Universal |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP. |
Header |
Ndis.h (include Ndis.h) |
Library |
Ndis.lib |
IRQL |
PASSIVE_LEVEL |
See also