ProtocolUnbindAdapter

ProtocolUnbindAdapter

VOID
   ProtocolUnbindAdapter(
       OUT PNDIS_STATUS Status,
       IN NDIS_HANDLE ProtocolBindingContext,
       IN NDIS_HANDLE UnbindContext
       );

ProtocolUnbindAdapter is a required function in any driver that registers a ProtocolBindAdapter function with the NDIS library.

Parameters

Status

Specifies the status of the unbinding operation as the value returned by NdisCloseAdapter, which can be either of the following:

NDIS_STATUS_SUCCESS

The binding was closed and all resources pertaining to that binding have been released.

NDIS_STATUS_PENDING

The request is being handled asynchronously, and the ProtocolCloseAdapterComplete function will complete the operation.

ProtocolBindingContext

Specifies the handle to a protocol-allocated context area in which the protocol driver maintains per-binding runtime state. The driver supplied this handle when it called NdisOpenAdapter.

UnbindContext

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

Comments

As the reciprocal of ProtocolBindAdapter, ProtocolUnbindAdapter releases all resources the driver allocated for per-binding network I/O operations with one possible exception: the driver-allocated context area designated by the ProtocolBindingContext handle.

ProtocolUnbindAdapter must call NdisCloseAdapter, which can, in turn, call the driver’s ProtocolCloseAdapterComplete function with the ProtocolBindingContext handle, so ProtocolUnbindAdapter cannot free the memory at ProtocolBindingContext unless NdisCloseAdapter returns NDIS_STATUS_SUCCESS.

Consequently, ProtocolUnbindAdapter should store the input UnbindContext handle in the area at ProtocolBindingContext before it calls NdisCloseAdapter. If this call is completed asynchronously, the ProtocolCloseAdapterComplete function will free all driver-allocated per-binding resources and call NdisCompleteUnbindAdapter with the UnbindContext handle.

If NdisCloseAdapter returns NDIS_STATUS_SUCCESS, ProtocolUnbindAdapter frees all per-binding resources, including the driver-allocated memory at ProtocolBindingContext, and calls NdisCompleteUnbindAdapter itself.

The ProtocolUnbindAdapter function of an NDIS intermediate driver makes a reciprocal call to NdisIMDeinitializeDeviceInstance. Such a driver's MiniportHalt function must release all driver-allocated resources associated with the intermediate driver's NIC before its virtual NIC is removed from the system.

As soon as ProtocolUnbindAdapter calls NdisCloseAdapter, the NdisBindingHandle originally returned by NdisOpenAdapter becomes invalid. The protocol cannot make any subsequent calls to NdisXxx functions with this handle, and the protocol cannot receive any indications from the underlying driver. However, if the underlying NIC is being removed to be reconfigured, NDIS will call the driver’s ProtocolBindAdapter function to re-establish the binding when the NIC is available again.

By default, ProtocolUnbindAdapter runs at IRQL PASSIVE_LEVEL in the context of a system thread.