ProtocolUnbindAdapterEx (Compact 2013)

  • Article

3/26/2014

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

Syntax

NDIS_STATUS
  ProtocolUnbindAdapterEx(
    IN NDIS_HANDLE  UnbindContext,
    IN NDIS_HANDLE  ProtocolBindingContext
   );

Parameters

  • UnbindContext
    The handle that identifies the NDIS context area for this unbind operation.
  • ProtocolBindingContext
    A handle to a context area allocated by the protocol driver. The protocol driver maintains the per-binding context information in this context area. The driver supplied this handle to NDIS when the driver called the NdisOpenAdapterEx function.

Return Value

ProtocolUnbindAdapterEx returns one of the following status values:

Value

Description

NDIS_STATUS_SUCCESS

ProtocolUnbindAdapterEx successfully unbound from an underlying miniport adapter.

NDIS_STATUS_PENDING

ProtocolUnbindAdapterEx did not complete the unbind operation and the operation will be completed asynchronously. The protocol driver must call the NdisCompleteUnbindAdapterEx function after the unbind operation is complete.

Remarks

ProtocolUnbindAdapterEx is a required function. As the reciprocal of the ProtocolBindAdapterEx function, NDIS calls ProtocolUnbindAdapterEx to release the resources that the driver allocated for network I/O operations that are specific to a binding. A protocol driver cannot fail an unbind operation.

Before calling ProtocolUnbindAdapterEx, NDIS pauses the protocol binding. To pause the binding, NDIS calls the ProtocolNetPnPEvent function and specifics a NetEventPause event.

ProtocolUnbindAdapterEx must call the NdisCloseAdapterEx function to close the binding to the underlying miniport adapter. If NdisCloseAdapterEx returns NDIS_STATUS_SUCCESS, the close operation is complete. If NdisCloseAdapterEx returns NDIS_STATUS_PENDING, NDIS calls the protocol driver's ProtocolCloseAdapterCompleteEx function after the close operation is complete.

Before calling NdisCloseAdapterEx, the protocol driver should clear the multicast address list and packet filters for the binding. The protocol driver sets the binding multicast address list to NULL, and the packet filter to zero. For more information, see OID_802_3_MULTICAST_LIST and OID_GEN_CURRENT_PACKET_FILTER. If applicable, the protocol driver should remove the wake up pattern with the OID_PNP_REMOVE_WAKE_UP_PATTERN OID and clear the receive side scaling parameters with the OID_GEN_RECEIVE_SCALE_PARAMETERS OID.

ProtocolUnbindAdapterEx must not free the memory at ProtocolBindingContext until the close operation is complete. NDIS passes the handle at ProtocolBindingContext to ProtocolCloseAdapterCompleteEx.

If the protocol driver has completed the unbind operation, ProtocolUnbindAdapterEx can return NDIS_STATUS_SUCCESS. If NdisCloseAdapterEx returns NDIS_STATUS_PENDING, ProtocolUnbindAdapterEx must wait for NDIS to call ProtocolCloseAdapterCompleteEx before it can return NDIS_STATUS_SUCCESS.

ProtocolUnbindAdapterEx can return NDIS_STATUS_PENDING to defer the completion of the unbind operation to a later time. If ProtocolUnbindAdapterEx returns NDS_STATUS_PENDING, the driver must eventually call the NdisCompleteUnbindAdapterEx function to complete the unbind operation. If the NdisCloseAdapterEx function returned NDIS_STATUS_PENDING, the driver can complete the unbind operation in ProtocolCloseAdapterCompleteEx. ProtocolUnbindAdapterEx can store the handle at UnbindContext in the context area at ProtocolBindingContext before it calls NdisCloseAdapterEx. If ProtocolUnbindAdapterEx stored the handle, ProtocolCloseAdapterCompleteEx can pass the handle to NdisCompleteUnbindAdapterEx to complete the unbind operation.

As soon as ProtocolUnbindAdapterEx calls NdisCloseAdapterEx, the handle obtained from the NdisOpenAdapterEx function at the NdisBindingHandle parameter becomes invalid. ProtocolUnbindAdapterEx cannot make any subsequent calls to NdisXxx functions by using this handle. The driver can get receive and status indications from the underlying miniport adapter until the close operation is complete.

NDIS calls ProtocolUnbindAdapterEx at IRQL = PASSIVE_LEVEL.

See Also

Reference

NDIS Protocol Driver Functions
NdisCloseAdapterEx
NdisCompleteUnbindAdapterEx
NdisOpenAdapterEx
OID_802_3_MULTICAST_LIST
OID_GEN_CURRENT_PACKET_FILTER
OID_PNP_REMOVE_WAKE_UP_PATTERN
ProtocolBindAdapterEx
ProtocolCloseAdapterCompleteEx
ProtocolNetPnPEvent