BIND_HANDLER callback function
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.
The ProtocolBindAdapter function is required to support Plug and Play. All NDIS protocol drivers must export a ProtocolBindAdapter function.
Syntax
BIND_HANDLER ProtocolBindAdapter;
VOID ProtocolBindAdapter(
_Out_ PNDIS_STATUS Status,
_In_ NDIS_HANDLE BindContext,
_In_ PNDIS_STRING DeviceName,
_In_ PVOID SystemSpecific1,
_In_ PVOID SystemSpecific2
)
{ ... }
Parameters
Status [out]
Pointer to a variable in which ProtocolBindAdapter returns the status of its operation(s), as one of the following values:NDIS_STATUS_SUCCESS
The driver completed initialization successfully and bound itself to the NIC driver that DeviceName specifies.NDIS_STATUS_PENDING
The protocol will complete the bind operation asynchronously with a call to NdisCompleteBindAdapter when it is ready to accept receives from the underlying driver and to send transmit, query, and set requests down to the underlying driver.NDIS_STATUS_XXX or NTSTATUS_XXX
The protocol's attempt to set up a binding failed or the protocol could not allocate the resources it needed to carry out network I/O operations. Usually, such an error status is propagated from an NdisXxx function or a kernel-mode support routine.
BindContext [in]
Specifies a handle, supplied by NDIS, that the protocol passes subsequently to NdisCompleteBindAdapter if the bind operation completes asynchronously.DeviceName [in]
Pointer to a buffered Unicode string that names an underlying NIC driver or virtual NIC driver to which ProtocolBindAdapter should bind.SystemSpecific1 [in]
Registry path pointer that is a required parameter to NdisOpenProtocolConfiguration. The protocol driver cannot use this pointer for any other purpose.SystemSpecific2 [in]
Reserved for system use.
Return value
None
Remarks
ProtocolBindAdapter performs dynamic binding operations whenever an underlying NIC to which the protocol can bind itself becomes available. In addition, ProtocolBindAdapter continues driver initialization operations that were deferred from the DriverEntry function to support Plug and Play (PnP). ProtocolBindAdapter allocates sufficient memory to maintain per-binding run-time state and calls NdisOpenAdapter with the given BindContext and DeviceName to bind to the underlying driver.
If NdisOpenAdapter returns NDIS_STATUS_PENDING, NDIS will call the driver's ProtocolOpenAdapterComplete function after the binding operation has completed. ProtocolBindAdapter should store the input BindContext handle in the area it allocated for per-binding state; the ProtocolBindContext handle it supplied to NdisOpenAdapter is an input parameter to the driver's ProtocolOpenAdapterComplete function, which must pass the BindContext handle to NdisCompleteBindAdapter. The underlying NIC driver returns NDIS_STATUS_ADAPTER_NOT_READY for any requests it receives while the open operation is pending. Consequently, ProtocolBindAdapter cannot call NdisRequest or NdisCoRequest to query the underlying driver if NdisOpenAdapter returns NDIS_STATUS_PENDING.
In these circumstances, ProtocolBindAdapter simply sets Status to NDIS_STATUS_PENDING and returns control, thereby deferring whatever actions the protocol takes to set up binding-specific state and to allocate binding-specific resources to ProtocolOpenAdapterComplete if this function is called with an input Status of NDIS_STATUS_SUCCESS.
Similarly, if NdisOpenAdapter returns an error status, ProtocolBindAdapter sets Status to the returned value, releases any per-binding resources the driver has allocated, and returns control immediately. Otherwise, a successful binding has been established and the protocol can receive indications from the underlying driver to its ProtocolStatus or ProtocolCoStatus, ProtocolReceivePacket or ProtocolCoReceivePacket, and/or ProtocolReceive functions.
Consequently, when NdisOpenAdapter returns NDIS_STATUS_SUCCESS, ProtocolBindAdapter allocates the resources the driver needs to carry out network I/O on the binding and sets up whatever binding-specific run-time state the protocol uses to track network I/O operations. If the driver's installation file installed adapter-specific configuration information in the protocol section of the registry, ProtocolBindAdapter calls NdisOpenProtocolConfiguration and NdisReadConfiguration to retrieve this information. For more information about driver installation files, see Device Installation Overview.
Depending on the underlying media, ProtocolBindAdapter also can call NdisCoRequest or NdisRequest to query the underlying driver (or NDIS) about the underlying driver's NIC-specific limits, such as its maximum frame size, transmit/receive buffer space, and so forth, to set up appropriate state for the binding.
After the open operation is complete, ProtocolBindAdapter can return NDIS_STATUS_SUCCESS to complete the binding operation. ProtocolBindAdapter can return NDIS_STATUS_PENDING to defer the completion of the binding operations to a later time. If ProtocolBindAdapter returns NDIS_STATUS_PENDING, the driver must call the NdisCompleteBindAdapter function after the binding operation is complete.
Any protocol bound to a connection-oriented NIC driver can assume that the underlying miniport driver both supports multipacket sends and indicates full-packet receives.
A protocol bound to a connectionless miniport driver can determine whether the underlying driver indicates full-packet receives by comparing the values that driver returns for the OID_GEN_CURRENT_LOOKAHEAD and OID_GEN_RECEIVE_BLOCK_SIZE queries the protocol passes to NdisRequest. If they are identical, the protocol will make no calls to NdisTransferData on this binding. The protocol can determine whether the underlying driver supports multipacket sends with the OID_GEN_MAXIMUM_SEND_PACKETS query. However, even if the underlying driver returns one, indicating that it does not have a MiniportSendPackets function, the protocol can still call NdisSendPackets on the binding, as long as the protocol does not supply out-of-band information with the packet descriptors it allocates for sends. NDIS handles the submission of packet arrays to such an underlying connectionless NIC driver transparently to bound protocols. The protocol is responsible for ensuring that the underlying driver is capable of handling protocol-supplied out-of-band data, if any.
For more information about general and medium-specific OID requests, see NDIS Object Identifiers.
A driver's Protocol(Co)ReceivePacket or ProtocolReceive function can be called as soon as the protocol sets up a packet filter with OID_GEN_CURRENT_PACKET_FILTER for the binding. For the NULL filter, receive indications are enabled on return from a successful call to NdisOpenAdapter.
Every NDIS protocol driver should allocate sufficient packet pool and buffer pool from which to allocate packet descriptors and buffer descriptors for subsequent network transmits and, possibly, for subsequent transfer-data requests, depending on whether the underlying driver indicates full-packet receives with NdisMIndicateReceivePacket or NdisMCoIndicateReceivePacket.
The ProtocolBindAdapter function of a connection-oriented call manager or MCM driver must call NdisCmRegisterAddressFamily or NdisMCmRegisterAddressFamily, respectively, to register its ProtocolCmXxx functions and signaling services for this adapter with NDIS. NDIS will advertise the call manager's services to possible client protocols by calling their ProtocolCoAfRegisterNotify functions, which each potential connection-oriented client registered when it called NdisRegisterProtocol from its DriverEntry function.
Note that connection-oriented client protocols cannot call NdisClOpenAddressFamily from their ProtocolBindAdapter functions. Instead, these protocols make this call to register their ProtocolClXxx functions with NDIS from their ProtocolCoAfRegisterNotify functions.
The ProtocolBindAdapter function of an NDIS intermediate driver is responsible for prompting the initialization of the driver's virtual NIC by calling NdisIMInitializeDeviceInstanceEx or NdisIMInitializeDeviceInstance, which, in turn, calls the driver's MiniportInitialize function. Such a driver must initialize its virtual NIC after ProtocolBindAdapter(or ProtocolBindAdapterComplete) establishes a binding to the underlying driver specified at DeviceName. Still higher level protocols cannot bind to such an intermediate driver until its virtual NIC has been initialized. If the intermediate driver sets up a device context area with NdisIMInitializeDeviceInstanceEx, higher level protocols that bind themselves to its virtual NIC subsequently can call NdisIMGetBindingContext to query the information that the intermediate driver provided.
If ProtocolBindAdapter cannot allocate the resources it needs to carry out subsequent network I/O operations, it should free all resources it has already allocated, set Status to an appropriate error value, and return control.
If the driver is ready to carry out network I/O on the established binding, ProtocolBindAdapter calls NdisCompleteBindAdapter with NDIS_STATUS_SUCCESS for the Status and OpenStatus arguments.
Requirements
Target platform |
Desktop |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use ProtocolBindAdapterEx instead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP |
Header |
Ndis.h (include Ndis.h) |
IRQL |
PASSIVE_LEVEL |
See also
DriverEntry of NDIS Protocol Drivers
NdisIMInitializeDeviceInstance
NdisIMInitializeDeviceInstanceEx