ProtocolBindAdapter

Article
06/30/2006

ProtocolBindAdapter is a required driver function to support Plug and Play.

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

Parameters

Status
Points 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 network adapter 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
Points to a buffered Unicode string naming an underlying network adapter driver or virtual network adapter 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.

Comments

ProtocolBindAdapter performs dynamic binding operations whenever an underlying network adapter 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 runtime 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 network adapter driver returns NDIS_STATUS_ADAPTER_NOT_READY for any requests it receives while the open operation is pending. Consequently, ProtocolBindAdapter cannot call Ndis(Co)Request 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 Protocol(Co)Status, Protocol(Co)ReceivePacket, 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 runtime 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 the Setup, Plug & Play, and Power Managment Design Guide and Reference.

Depending on the underlying media, ProtocolBindAdapter also can call NdisCoRequest or NdisRequest to query the underlying driver (or NDIS) about the underlying driver's network adapter-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 network adapter driver can assume that the underlying miniport both supports multipacket sends and indicates full-packet receives.

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 network adapter by calling NdisIMInitializeDeviceInstanceEx or NdisIMInitializeDeviceInstance, which, in turn, calls the driver's MiniportInitialize function. Such a driver must initialize its virtual network adapter 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 network adapter has been initialized.

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

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	2.0 and later	Ndis.h		Ndislib.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

Last updated on Tuesday, July 13, 2004

ProtocolBindAdapter

Additional resources