Activating an NDIS Port

After a miniport driver successfully allocates an NDIS port, and before using the port number in NDIS functions, the driver must activate the port. To activate the port, the miniport driver sends a port activation Plug and Play (PnP) event to NDIS. To send the port activation PnP event, miniport drivers use the NetEventPortActivation PnP event code in the call to the NdisMNetPnPEvent function.

To activate ports, the miniport driver must set the members of the NET_PNP_EVENT_NOTIFICATION structure that the NetPnPEvent parameter of NdisMNetPnPEvent points to as follows:

PortNumber
The source port of the event notification. Set this member to zero because the port numbers are provided in the Buffer member of the structure that the NetPnPEvent member specifies.

NetPnPEvent
A NET_PNP_EVENT structure that describes the port activation event. Set the members of this structure as follows:

NetEvent
An event code that describes the event. Set this member to NetEventPortActivation.

Buffer
A pointer to a linked list of NDIS_PORT structures. The Next member of the NDIS_PORT structures points to the next NDIS_PORT structure in the list.

BufferLength
The number of bytes that are specified in Buffer . Set BufferLength to the size of the NDIS_PORT structures.

Other members
Set the remaining members of NET_PNP_EVENT to NULL.

The miniport driver lists the ports that have changed states from inactive to active in a linked list of NDIS_PORT structures. However, if the default port of a miniport adapter is the target of a NetEventPortActivation PnP event, the default port must be the only port in the list.

When the miniport driver notifies NDIS of the activation of a port (and possibly before this notification call returns), the miniport driver must be ready to handle send requests and OID requests that are associated with the port. Miniport drivers must not use the port number of a newly activated port in status or receive indications until after the call to NdisMNetPnPEvent returns.

NDIS does not notify overlying drivers about activated ports until after the default port is active. When NDIS calls the ProtocolBindAdapterEx function of a protocol driver, NDIS provides a list of all currently active ports in the ActivePorts member of the NDIS_BIND_PARAMETERS structure that the BindParameters parameter points to. When a miniport driver activates new ports, NDIS notifies all of the protocol drivers that are bound to the miniport driver with the NetEventPortActivation PnP event. For more information about handling these port activation events in a protocol driver, see Handling the Port Activation PnP Event.

Before a miniport driver allocates an NDIS port, the driver must call the NdisMSetMiniportAttributes function to set the registration attributes in the NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES structure. Miniport drivers can control the activation of the default port by setting the NDIS_MINIPORT_CONTROLS_DEFAULT_PORT attribute flag when they call NdisMSetMiniportAttributes. If a miniport driver assumes the responsibility for activating the default port, NDIS does not initiate the binding between the miniport adapter and the overlying drivers until the miniport driver activates the default port with the port activation PnP event.

All of the ports that are specified by the linked list of NDIS_PORT structures must be in the allocated state. A miniport driver should not attempt to activate a port that is already active; if the driver does attempt to activate an active port, NDIS treates the situation as a port activation failure.

If NDIS fails to activate any ports on the list, it fails the call to NdisMNetPnPEvent, and none of the ports on the list change state to the activated state. If NDIS fails to activate the ports because some of the ports do not exist, NdisMNetPnPEvent returns an NDIS_STATUS_INVALID_PORT return value. If NDIS fails to activate the ports because some of the ports are not in the allocated state, NdisMNetPnPEvent returns an NDIS_STATUS_INVALID_PORT_STATE return value.

After a port has been successfully activated, the port is in the activated state. Miniport drivers can indicate received data and status for a port in the activated state.

NDIS passes the authentication state of the default port to the MiniportInitializeEx function at the DefaultPortAuthStates member of the NDIS_MINIPORT_INIT_PARAMETERS structure. If a miniport driver controls the default port, when the miniport driver activates the default port, it can activate the default port by using the default authentication settings. To use the default authentication settings, set the NDIS_PORT_CHAR_USE_DEFAULT_AUTH_SETTINGS flag in the Flags member of NDIS_PORT_CHARACTERISTICS structure. Miniport drivers can use the NDIS_PORT_CHAR_USE_DEFAULT_AUTH_SETTINGS flag for the ports that they allocate and activate. For the activation case, NDIS assigns the default authentication states to the newly activated port and ignores the authentication states that are passed to NdisMNetPnPEvent for the NetEventPortActivation event.

For more information about controlling the default port and allocating ports, see Allocating NDIS Ports.