Share via

NdisMSetMiniportSecondary (Compact 2013)

  • Article

3/26/2014

This function sets the specified miniport adapter to the secondary role in relation to the primary miniport adapter. The primary miniport 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 adapter.

Syntax

NDIS_STATUS NdisMSetMiniportSecondary(
  NDIS_HANDLE MiniportAdapterHandle,
  NDIS_HANDLE PrimaryMiniportAdapterHandle
);

Parameters

  • MiniportAdapterHandle
    [in] Specifies the handle to the miniport adapter previously input to MiniportInitialize.
  • PrimaryMiniportAdapterHandle
    [in] Specifies the handle to the primary miniport adapter that has already been initialized with MiniportInitialize.

Return Value

The following table shows the return values for this function.

Value

Description

NDIS_STATUS_SUCCESS

The miniport adapter has been set to the secondary role in relation to the primary miniport adapter. The miniport driver can subsequently promote the secondary miniport adapter to the primary role.

NDIS_STATUS_FAILURE

An attempt to set the miniport 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 adapter, that is, from within the miniport's MiniportInitialize function. In this call, the miniport driver passes the handle to the miniport adapter being initialized in the MiniportAdapterHandle parameter and the handle to the primary miniport adapter that has already been initialized in the PrimaryMiniportAdapterHandle parameter. The primary miniport 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 adapter. For example, NDIS might query all miniport adapters for their media connectivity. The secondary miniport adapter must process and respond to this query.

After initialization of the secondary miniport adapter, the miniport driver can subsequently call the NdisMPromoteMiniport function to promote the secondary miniport adapter to the primary role.

Before the miniport driver calls NdisMSetMiniportSecondary, it must first determine if the miniport adapter being initialized is part of the miniport's bundle of miniport adapters. A miniport driver uses this bundle to balance the workload that each miniport adapter carries and to enable a secondary miniport adapter to take over packet transfers and information requests if the primary miniport adapter fails. 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 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's registry key. The miniport driver should copy the string value to the miniport's internal structure in which the miniport stores information specific to the miniport 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-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 adapters.

A miniport driver can call NdisMSetMiniportSecondary during the subsequent initialization of several miniport adapters to set them all to secondary roles. That is, multiple secondary miniport 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 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-adapter instances that are initialized by the same miniport driver and that belong to the miniport's bundle can call NdisMSetMiniportSecondary.

Requirements

Header

ndis.h

Library

ndis.dll

See Also

Reference

NDIS 5.x Legacy Functions
MiniportInitialize
NdisMPromoteMiniport
NdisMRemoveMiniport
NdisOpenConfiguration
NdisReadConfiguration