Opening an Adapter Underlying a Protocol Driver (NDIS 5.1)
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.
Whenever an underlying NIC to which a protocol driver can bind itself becomes available, NDIS calls the protocol's ProtocolBindAdapterfunction. The protocol driver typically reads adapter-specific configuration information from the registry and calls NdisOpenAdapterto set up a binding to the adapter.
To obtain a handle to the registry key that contains adapter-specific information, a protocol driver calls NdisOpenProtocolConfigurationwith the ProtocolSectionparameter set to the SystemSpecific1value that was passed to the protocol driver's ProtocolBindAdapterfunction. The protocol driver can call NdisReadConfigurationand NdisWriteConfigurationto read and write adapter-specific information. It can call NdisOpenConfigurationKeyByIndexor NdisOpenConfigurationKeyByNameto obtain a handle to a subkey of the registry key opened with NdisOpenProtocolConfiguration.
To bind to an underlying NIC and the miniport driver that controls it, a protocol driver calls NdisOpenAdapter. A protocol driver passes a handle at the ProtocolBindingContextparameter to a binding-specific context area that it allocated to store state information for the binding. NDIS will pass this handle back to the protocol driver in subsequent calls pertaining to the binding, for example, in calls to ProtocolReceive, ProtocolStatus, or ProtocolCoStatus.
NDIS returns a handle to the protocol driver in the NdisBindingHandleparameter of NdisOpenAdapter. This handle must be retained by the protocol, usually in its binding-specific context area. The protocol driver must pass this handle to NDIS in future calls relating to this binding, such as calls to NdisSend, NdisSendPackets, or NdisCoSendPackets.
The protocol driver passes the name of the adapter from the DeviceNameparameter of ProtocolBindAdapterto the AdapterNameparameter of NdisOpenAdapter.
The DeviceNameparameter is valid only in the context of the call to ProtocolBindAdapter. If the protocol driver calls NdisOpenAdapterfrom a different thread context (after returning NDIS_STATUS_PENDING from ProtocolBindAdapter), it must copy the string indicated by DeviceNameand pass a pointer to the new string to NdisOpenAdapter.
The protocol driver passes the types of mediums it supports to the MediumArrayparameter of NdisOpenAdapter. If the call to NdisOpenAdaptersucceeds, NDIS selects a medium from MediumArrayand returns its index in the SelectedMediumIndexparameter. The value that the protocol driver passes to the NdisProtocolHandleparameter is the value returned to the protocol driver from a successful call to NdisRegisterProtocol.
If a protocol driver cannot successfully bind to an underlying adapter (for example, if NdisOpenAdapterreturns an error), it should deallocate any resources it previously allocated for that binding. If the protocol driver cannot successfully open any of the possible adapters, it should deallocate any global resources the protocol has previously allocated and return an appropriate failure status. Typically, the protocol driver's ProtocolBindAdapterfunction should log failed binding attempts with appropriate descriptive information by calling NdisWriteEventLogEntry.