2.3 Dynamic Binding in a Protocol Driver

A PnP-ready protocol driver can support dynamic binding to underlying NICs by providing both a ProtocolBindAdapter function and a ProtocolUnbindAdapter function.

If a driver registers these functions with NDIS, it indicates that it will defer opening and binding to an underlying NIC as is otherwise done in the DriverEntry function and, instead, perform these actions in its ProtocolBindAdapter function. If a protocol provides these dynamic-bind functions, whenever an underlying NIC becomes available, NDIS will call the ProtocolBindAdapter function of any protocol driver that can bind itself to that adapter, and whenever an underlying NIC is closed, NDIS will call the reciprocal ProtocolUnbindAdapter function.

ProtocolBindAdapter is declared as follows:

VOID
ProtocolBindAdapter(
OUT PNDIS_STATUS Status,
IN NDIS_HANDLE BindContext,
IN PNDIS_STRING DeviceName,
IN PVOID SystemSpecific1,
IN PVOID SystemSpecific2
);

NDIS supplies the name of the newly available adapter for ProtocolBindAdapter to open at DeviceName. NDIS passes a handle at BindContext that represents its context for the bind request. The protocol driver must retain this handle and pass it back to NDIS as a parameter to NdisCompleteBindAdapter when the driver has completed its binding-related activities and is ready to transmit and receive packets.

Binding-time actions include allocating and initializing an adapter-specific context area for the binding, and calling NdisOpenAdapter to open the adapter passed at DeviceName. DeviceName might refer to an underlying NIC or it can be the name of a virtual NIC exported by an NDIS intermediate driver that is layered between the protocol driver and the NIC driver managing the adapter to which transmit requests are directed. For instance, an intermediate NDIS driver can translate between the format of the medium supported by a legacy protocol driver and the format of the medium supported by an underlying NIC driver. The protocol-allocated context area or a comparable location should be used to store the BindContext.

The BindContext value must be stored because NdisOpenAdapter can return NDIS_STATUS_PENDING. If NdisOpenAdapter returns a pending status, the protocol driver cannot call NdisCompleteBindAdapter until the open operation is complete and the protocol driver is called at its ProtocolOpenAdapterComplete function. In this case, BindContext must be retrieved from a known location and passed to NdisCompleteBindAdapter.

SystemSpecific1 is a string that must be passed to NdisOpenProtocolConfiguration. This string is opaque to protocol drivers.

SystemSpecific2 is reserved for system use.

For more information about dynamic unbinding, see Section 2.7.