UNBIND_HANDLER callback function
Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.
The ProtocolUnbindAdapter function requests that a protocol driver unbind from an underlying miniport driver.
Syntax
UNBIND_HANDLER ProtocolUnbindAdapter;
VOID ProtocolUnbindAdapter(
_Out_ PNDIS_STATUS Status,
_In_ NDIS_HANDLE ProtocolBindingContext,
_In_ NDIS_HANDLE UnbindContext
)
{ ... }
Parameters
Status [out]
A pointer to a variable in which ProtocolUnbindAdapter returns the status of the unbind operation as one of the following values:NDIS_STATUS_SUCCESS
The binding was closed and all resources pertaining to that binding have been released.NDIS_STATUS_PENDING
ProtocolUnbindAdapter did not complete the unbind operation, and the operation will be completed asynchronously. The protocol driver must call the NdisCompleteUnbindAdapter function after the unbind operation is complete.
ProtocolBindingContext [in]
Specifies the handle to a protocol-allocated context area in which the protocol driver maintains per-binding run-time state. The driver supplied this handle when it called NdisOpenAdapter.UnbindContext [in]
Specifies a handle, supplied by NDIS, that the protocol passes subsequently to NdisCompleteUnbindAdapter.
Return value
None
Remarks
The ProtocolUnbindAdapter function is a required function. As the reciprocal of ProtocolBindAdapter, ProtocolUnbindAdapter releases all resources that 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 the NdisCloseAdapter function to close the binding to the underlying miniport adapter. If NdisCloseAdapter returns NDIS_STATUS_SUCCESS, the close operation is complete. If NdisCloseAdapter returns NDIS_STATUS_PENDING, NDIS calls the protocol driver's ProtocolCloseAdapterComplete function after the close operation is complete.
In the ProtocolBindingContext parameter of ProtocolCloseAdapterComplete, NDIS passes a handle to the driver's context for the binding. ProtocolUnbindAdapter must not 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 ProtocolUnbindAdapter is completed asynchronously, the ProtocolCloseAdapterComplete function frees all driver-allocated per-binding resources and calls the NdisCompleteUnbindAdapter function with the UnbindContext handle.
Before calling NdisCloseAdapter, 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.
If the protocol driver has completed the unbind operation, ProtocolUnbindAdapter can return NDIS_STATUS_SUCCESS, free all per-binding resources, including the driver-allocated memory at ProtocolBindingContext, and call NdisCompleteUnbindAdapter.
If NdisCloseAdapter returns NDIS_STATUS_PENDING, ProtocolUnbindAdapter must wait for NDIS to call ProtocolCloseAdapterComplete before it can return NDIS_STATUS_SUCCESS.
ProtocolUnbindAdapter can return NDIS_STATUS_PENDING to defer the completion of the unbind operation to a later time. If ProtocolUnbindAdapter returns NDIS_STATUS_PENDING, the driver must eventually call the NdisCompleteUnbindAdapter function to complete the unbind operation.
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 should be considered invalid. ProtocolUnbindAdapter 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 reestablish the binding when the NIC is available again.
Requirements
Target platform |
Desktop |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use ProtocolUnbindAdapterExinstead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP |
Header |
Ndis.h (include Ndis.h) |
IRQL |
PASSIVE_LEVEL |
See also
NdisIMDeinitializeDeviceInstance