ProtocolBindAdapter

The ProtocolBindAdapter function is required to support Plug and Play. All NDIS protocol drivers must export a ProtocolBindAdapter function.

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

Parameters

Status

Pointer to a variable in which ProtocolBindAdapter returns the status of its operation(s), as one of the following:

NDIS_STATUS_SUCCESS

The driver completed initialization successfully and bound itself to the given NIC driver specified at DeviceName.

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

Specifies a handle, supplied by NDIS, that the protocol passes subsequently to NdisCompleteBindAdapter.

DeviceName

Pointer to a buffered Unicode string naming an underlying NIC driver or virtual NIC driver to which ProtocolBindAdapter should bind.

SystemSpecific1

Specifies a registry path pointer that is a required parameter to NdisOpenProtocolConfiguration. The caller cannot use this pointer for any other purpose.

SystemSpecific2

Reserved for system use. The caller cannot use this pointer for any purpose.

Headers

Declared in Ndis.h. Include Ndis.h.

Comments

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 deferred from the DriverEntry function to support Plug and Play. ProtocolBindAdapter allocates sufficient memory to maintain per-binding run-time state and calls NdisOpenAdapter with the given BindContext and DeviceName to bind itself to the underlying driver.

If NdisOpenAdapter returns NDIS_STATUS_PENDING, the driver’s ProtocolOpenAdapterComplete function will be called subsequently when 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 subsequently. 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 script 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 scripts, 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.

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 signalling 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.

ProtocolBindAdapter runs at IRQL = PASSIVE_LEVEL.

See Also

DriverEntry of NDIS Protocol Drivers, MiniportInitialize, MiniportSendPackets, NdisAllocateBufferPool, NdisAllocateMemoryWithTag, NdisAllocatePacketPool, NdisClOpenAddressFamily, NdisCmRegisterAddressFamily, NdisCompleteBindAdapter, NdisCoRequest, NdisCoSendPackets, NdisIMGetBindingContext, NdisIMInitializeDeviceInstance, NdisIMInitializeDeviceInstanceEx, NdisInitUnicodeString, NdisMCmRegisterAddressFamily, NdisMCoIndicateReceivePacket, NdisMIndicateReceivePacket, NdisOpenAdapter, NdisOpenProtocolConfiguration, NDIS_PACKET_OOB_DATA, NdisReadConfiguration, NdisRequest, NDIS_REQUEST, ProtocolCoAfRegisterNotify, ProtocolCoReceivePacket, ProtocolCoStatus, ProtocolOpenAdapterComplete, ProtocolReceive, ProtocolReceivePacket, ProtocolStatus, ProtocolUnbindAdapter