ProtocolBindAdapter (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/2010

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

Syntax

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

Parameters

Status
[out] Points to a variable in which ProtocolBindAdapter returns the status of its operations.

BindContext
[in] Specifies a handle (supplied by NDIS) that the protocol passes subsequently to NdisCompleteBindAdapter.

DeviceName
[in] Points to a buffered Unicode string naming an underlying network adapter driver or virtual network adapter driver to which ProtocolBindAdapter should bind.

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

SystemSpecific2
[in] Reserved for system use. The caller cannot use this pointer for any purpose.

Return Value

The following table shows the return values for this function.

Value	Description
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.

Remarks

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 Initialization of NDIS Protocol Drivers process 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 NdisRequest 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, ProtocolReceivePacket, 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.

Depending on the underlying media, ProtocolBindAdapter also can call 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.

A driver's ProtocolReceivePacket 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.

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 establishes a binding to the underlying driver specified at DeviceName. Protocols that are even higher levels 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

Header	ndis.h
Library	Ndislib.lib
Windows Embedded CE	Windows CE .NET 4.0 and later

ProtocolBindAdapter (Windows Embedded CE 6.0)

Syntax

Parameters

Return Value

Remarks

Requirements

See Also

Reference

Concepts

Additional resources