ProtocolBindAdapterEx (Compact 2013)

Article
07/31/2017

3/26/2014

NDIS calls a protocol driver's ProtocolBindAdapterEx function to request the driver to bind to a miniport adapter.

Syntax

NDIS_STATUS
  ProtocolBindAdapterEx(
    IN NDIS_HANDLE  ProtocolDriverContext,
    IN NDIS_HANDLE  BindContext,
    IN PNDIS_BIND_PARAMETERS  BindParameters
   );

Parameters

ProtocolDriverContext
A handle to a driver-allocated context area where the driver maintains state and configuration information. The protocol driver passed this context area to the NdisRegisterProtocolDriver function.

BindContext
The handle that identifies the NDIS context area for this bind operation.

BindParameters
A pointer to an NDIS_BIND_PARAMETERS structure that NDIS created.

Return Value

ProtocolBindAdapterEx returns one of the following status values:

Value	Description
NDIS_STATUS_SUCCESS	ProtocolBindAdapterEx successfully completed the binding to the underlying miniport adapter.
NDIS_STATUS_PENDING	ProtocolBindAdapterEx did not complete the bind operation and the operation will be completed asynchronously. The protocol driver must call the NdisCompleteBindAdapterEx function when the operation is completed.
NDIS_STATUS_RESOURCES	ProtocolBindAdapterEx could not allocate the resources that the driver requires to perform network I/O operations.
NDIS_STATUS_XXX or NTSTATUS_XXX	The protocol driver's attempt to set up a binding failed. Usually, such an error status is propagated from an NdisXxx function or a kernel-mode support routine.

Remarks

ProtocolBindAdapterEx is a required function. NDIS calls ProtocolBindAdapterEx to perform binding operations when an underlying miniport adapter, to which the protocol driver can bind, becomes available.

ProtocolBindAdapterEx allocates sufficient memory to maintain the binding context information and calls the NdisOpenAdapterEx function to bind itself to the underlying miniport adapter. ProtocolBindAdapterEx passes a pointer to the binding context information at the ProtocolBindingContext parameter of NdisOpenAdapterEx. ProtocolBindAdapterEx passes the value at the AdapterName member from its BindParameters parameter as the AdapterName member of the OpenParameters parameter of NdisOpenAdapterEx.

Before the driver calls NdisOpenAdapterEx, the driver can pass the pointer at BindParameters to the NdisOpenConfigurationEx function to read the configuration parameters that are associated with a miniport adapter.

After opening the miniport adapter successfully, the driver can pass the handle from NdisHandle parameter of NdisOpenAdapterEx to NdisOpenConfigurationEx to obtain a handle to the registry location where the configuration parameters for a protocol binding are stored.

ProtocolBindAdapterEx passes NdisOpenAdapterEx a pointer to an array of medium type values that lists the types of media that the protocol driver can support. This list is a subset of the NDIS NdisMediumXxx Types types. NDIS indicates the selected medium type at the SelectedMediumIndex parameter of the structure at OpenParameters.

If NdisOpenAdapterEx returns an error status, ProtocolBindAdapterEx returns that error status, releases any per-binding resources that the protocol driver allocated, and returns control immediately.

If NdisOpenAdapterEx returns NDIS_STATUS_SUCCESS, ProtocolBindAdapterEx can allocate the remaining resources that the protocol driver has to perform network I/O on the binding. The driver can also configure any binding-specific context information that the driver uses to track network I/O operations.

If NdisOpenAdapterEx returns NDIS_STATUS_PENDING, NDIS calls the protocol driver's ProtocolOpenAdapterCompleteEx function after the open operation is complete. ProtocolOpenAdapterCompleteEx can complete the binding operations. ProtocolBindAdapterEx can store the BindContext handle in the binding context area. NDIS passes ProtocolBindingContext as an input parameter to the driver's ProtocolOpenAdapterCompleteEx function.

If NdisOpenAdapterEx returns NDIS_STATUS_PENDING, NDIS sets the SelectedMediumIndex member of the structure at the OpenParameters parameter and the value of the NdisBindingHandle parameter after NdisOpenAdapterEx returns. NDIS sets these values before it calls ProtocolOpenAdapterCompleteEx. Therefore, the protocol driver must store the open parameters structure, and the protocol binding handle in the context area at ProtocolBindingContext (or any location that is valid until NDIS calls ProtocolOpenAdapterCompleteEx).

A protocol driver cannot make OID requests on a binding until the open operation is complete. Because the binding is in the paused state after the open operation is complete, the protocol driver cannot make send requests until after NDIS restarts the binding.

After the open operation is complete, ProtocolBindAdapterEx can return NDIS_STATUS_SUCCESS to complete the binding operation. ProtocolBindAdapterEx can return NDIS_STATUS_PENDING to defer the completion of the binding operations to a later time. If ProtocolBindAdapterEx returns NDIS_STATUS_PENDING, the driver must call the NdisCompleteBindAdapterEx function after the binding operation is complete.

Protocol drivers should use the NDIS_BIND_PARAMETERS structure to determine the underlying miniport adapter's capabilities. After the open operation is complete, depending on the underlying media, the protocol driver can call the NdisOidRequest function to query the underlying miniport driver (or NDIS) about additional miniport adapter capabilities.

NDIS can call a protocol driver's ProtocolReceiveNetBufferLists function after the driver sets up a packet filter for the binding with the OID_GEN_CURRENT_PACKET_FILTER OID. If the underlying miniport adapter does not use a packet filter for incoming packets, receive indications are enabled after the open operation is complete. Protocol drivers can receive status indications at the ProtocolStatusEx function after the open operation is complete.

Every protocol driver should allocate sufficient NET_BUFFER and NET_BUFFER_LIST structure pools. The driver allocates network data descriptors from these pools for subsequent send operations.

If ProtocolBindAdapterEx cannot allocate the resources it needs to carry out subsequent network I/O operations, it should free all resources it has already allocated, and return an appropriate error value.

NDIS calls a protocol driver's ProtocolUnbindAdapterEx function to request the driver to unbind from an underlying miniport adapter.

If the protocol driver successfully opens the miniport adapter but the bind operation fails (for example, because of a failed OID request), the driver must close the miniport adapter from within the context of ProtocolBindAdapterEx or ProtocolUnbindAdapterEx. For example, the driver calls NdisCloseAdapterEx from ProtocolBindAdapterEx and waits for the close operation to complete before the driver returns from ProtocolBindAdapterEx. Alternatively if the driver returned NDIS_STATUS_PENDING from ProtocolBindAdapterEx, the driver can call the NdisUnbindAdapter function and call NdisCloseAdapterEx in the ProtocolUnbindAdapterEx function.

NDIS calls ProtocolBindAdapterEx at IRQL = PASSIVE_LEVEL.

ProtocolBindAdapterEx (Compact 2013)

Syntax

Parameters

Return Value

Remarks

See Also

Reference

Additional resources