1.2.1  Opening an Adapter Underlying an Intermediate Driver

ProtocolBindAdapter uses the value at DeviceName to open an underlying NIC or virtual NIC, thereby establishing a binding to the underlying NIC driver. It can also read additional configuration information it requires from the registry. NdisOpenProtocolConfiguration is called to obtain a handle to the registry key where the intermediate driver stores any adapter-specific information, and the NdisRead(Write)Configuration functions are called to read and write such information. The NdisRead(Write)Configuration functions are described in the Network Driver Reference.

Typically, ProtocolBindAdapter uses the context area it allocates to represent its binding to DeviceName as storage for any binding-specific information associated with the bound adapter.

Binding is accomplished by calling NdisOpenAdapter, declared as follows:

VOID
   NdisOpenAdapter(
       OUT PNDIS_STATUS    Status,
       OUT PNDIS_STATUS    OpenErrorStatus,
       OUT PNDIS_HANDLE    NdisBindingHandle,
       OUT PUINT    SelectedMediumIndex,
       IN PNDIS_MEDIUM    MediumArray,
       IN UINT    MediumArraySize,
       IN NDIS_HANDLE    NdisProtocolHandle,
       IN NDIS_HANDLE    ProtocolBindingContext,
       IN PNDIS_STRING    AdapterName,
       IN UINT    OpenOptions,
       IN PSTRING    AddressingInformation
       );

An intermediate driver passes a handle at ProtocolBindingContext that represents the binding-specific context area it allocated and initialized. NDIS will pass this context back to the intermediate driver in future calls pertaining to the binding, for instance, in calls to ProtocolReceive or ProtocolStatus. Similarly, NDIS will pass a handle at NdisBindingHandle to the intermediate driver when NdisOpenAdapter returns. This handle must be retained by the intermediate driver, usually in its binding-specific context area. The intermediate driver passes this handle to NDIS in future calls relating to this binding, such as calls to NdisSend or NdisSendPackets.

ProtocolBindAdapter also passes the type(s) of medium(s) it supports at MediumArray. If NdisOpenAdapter is successful, the underlying NIC driver will select a medium it can support and return the index of the selected medium from MediumArray at SelectedMediumIndex.

ProtocolBindAdapter passes the value returned from a previous successful call to NdisRegisterProtocol at NdisProtocolHandle.

If NdisOpenAdapter returns an error, the intermediate driver should deallocate the memory used for the context area and release any other resources it allocated for the binding. Typically, ProtocolBindAdapter logs any failed binding operations with appropriate descriptive information by calling NdisWriteErrorLogEntry.