PROTOCOL_UNBIND_ADAPTER_EX función de devolución de llamada (ndis.h)

Artículo
08/07/2023

NDIS llama a la función ProtocolUnbindAdapterEx de un controlador de protocolo para solicitar al controlador que se desenlace de un adaptador de miniport subyacente.

Nota Debe declarar la función mediante el tipo PROTOCOL_UNBIND_ADAPTER_EX . Para obtener más información, consulte la sección Ejemplos siguientes.

Sintaxis

PROTOCOL_UNBIND_ADAPTER_EX ProtocolUnbindAdapterEx;

NDIS_STATUS ProtocolUnbindAdapterEx(
  [in] NDIS_HANDLE UnbindContext,
  [in] NDIS_HANDLE ProtocolBindingContext
)
{...}

Parámetros

[in] UnbindContext

Identificador que identifica el área de contexto de NDIS para esta operación de desenlace.

[in] ProtocolBindingContext

Identificador de un área de contexto asignada por el controlador de protocolo. El controlador de protocolo mantiene la información de contexto por enlace en este área de contexto. El controlador proporcionó este identificador a NDIS cuando el controlador llamó a la función NdisOpenAdapterEx .

Valor devuelto

ProtocolUnbindAdapterEx devuelve uno de los siguientes valores de estado:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	ProtocolUnbindAdapterEx desenlace correctamente desde un adaptador de minipuerto subyacente.
NDIS_STATUS_PENDING	ProtocolUnbindAdapterEx no completó la operación de desenlace y la operación se completará de forma asincrónica. El controlador de protocolo debe llamar a Función NdisCompleteUnbindAdapterEx una vez completada la operación de desenlace.

Comentarios

ProtocolUnbindAdapterEx es una función necesaria. Como recíproca de la función ProtocolBindAdapterEx , NDIS llama a ProtocolUnbindAdapterEx para liberar los recursos asignados al controlador para las operaciones de E/S de red específicas de un enlace. Un controlador de protocolo no puede producir un error en una operación de desenlace.

Antes de llamar a ProtocolUnbindAdapterEx, NDIS pausa el enlace de protocolo. Para pausar el enlace, NDIS llama a la función ProtocolNetPnPEvent y especifica un evento NetEventPause .

ProtocolUnbindAdapterEx debe llamar a la función NdisCloseAdapterEx para cerrar el enlace al adaptador de miniport subyacente. Si NdisCloseAdapterEx devuelve NDIS_STATUS_SUCCESS, se completa la operación de cierre. Si NdisCloseAdapterEx devuelve NDIS_STATUS_PENDING, NDIS llama al controlador del protocolo. Función ProtocolCloseAdapterCompleteEx una vez completada la operación de cierre.

Antes de llamar a NdisCloseAdapterEx, el controlador de protocolo debe borrar la lista de direcciones de multidifusión y los filtros de paquetes para el enlace. El controlador de protocolo establece la lista de direcciones de multidifusión de enlace en NULL y el filtro de paquetes en cero. Para obtener más información, consulte OID_802_3_MULTICAST_LIST y OID_GEN_CURRENT_PACKET_FILTER.

Si se ha especificado un patrón de reactivación, el controlador de protocolo debe quitarlo con el OID de OID_PNP_REMOVE_WAKE_UP_PATTERN y borrar los parámetros de escalado lateral de recepción con el OID de OID_GEN_RECEIVE_SCALE_PARAMETERS . Un controlador de protocolo NDIS 6.20 y versiones posteriores debe quitar un patrón wake-on-LAN con el OID de OID_PM_REMOVE_WOL_PATTERN y quitar una descarga de protocolo de baja potencia con el OID de OID_PM_REMOVE_PROTOCOL_OFFLOAD .

ProtocolUnbindAdapterEx no debe liberar la memoria en ProtocolBindingContext hasta que se complete la operación de cierre. NDIS pasa el identificador en ProtocolBindingContext a ProtocolCloseAdapterCompleteEx.

Si el controlador de protocolo ha completado la operación de desenlace, ProtocolUnbindAdapterEx puede devolver NDIS_STATUS_SUCCESS. Si NdisCloseAdapterEx devuelve NDIS_STATUS_PENDING, ProtocolUnbindAdapterEx debe esperar a que NDIS llame a ProtocolCloseAdapterCompleteEx para poder devolver NDIS_STATUS_SUCCESS.

ProtocolUnbindAdapterEx puede devolver NDIS_STATUS_PENDING para aplazar la finalización de la operación de desenlace en un momento posterior. Si ProtocolUnbindAdapterEx devuelve NDIS_STATUS_PENDING, el controlador debe llamar finalmente al Función NdisCompleteUnbindAdapterEx para completar la operación de desenlace. Si la función NdisCloseAdapterEx devolvió NDIS_STATUS_PENDING, el controlador puede completar la operación de desenlace en ProtocolCloseAdapterCompleteEx. ProtocolUnbindAdapterEx puede almacenar el identificador en UnbindContext en el área de contexto de ProtocolBindingContext antes de llamar a NdisCloseAdapterEx. Si ProtocolUnbindAdapterEx almacenó el identificador, ProtocolCloseAdapterCompleteEx puede pasar el identificador a NdisCompleteUnbindAdapterEx para completar la operación de desenlace.

Tan pronto como ProtocolUnbindAdapterEx llama a NdisCloseAdapterEx, el identificador obtenido de la función NdisOpenAdapterEx en el parámetro NdisBindingHandle deja de ser válido. ProtocolUnbindAdapterEx no puede realizar llamadas posteriores a las funciones NdisXxx con este identificador. El controlador puede obtener indicaciones de recepción y estado del adaptador de miniporte subyacente hasta que se complete la operación de cierre.

NDIS llama a ProtocolUnbindAdapterEx en IRQL = PASSIVE_LEVEL.

Actualización de la administración de energía y la configuración rss

Los controladores de protocolo NDIS 6.0 y 6.1 deben realizar las siguientes operaciones cuando corresponda:

Quitar los patrones de reactivación de administración de energía en LAN (WOL) del adaptador de minipuerto con el OID_PNP_REMOVE_WAKE_UP_PATTERN OID.
Borre los parámetros de escalado del lado de recepción con . OID_GEN_RECEIVE_SCALE_PARAMETERS OID.

Los controladores de protocolo NDIS 6.20 y versiones posteriores deben realizar las siguientes operaciones:

Quite los patrones WOL de administración de energía del adaptador de minipuerto con el OID de OID_PM_REMOVE_WOL_PATTERN .
Eliminación de las descargas del protocolo de administración de energía del adaptador de miniporte con OID_PM_REMOVE_PROTOCOL_OFFLOAD OID.

Ejemplos

Para definir una función ProtocolUnbindAdapterEx , primero debe proporcionar una declaración de función que identifique el tipo de función que está definiendo. Windows proporciona un conjunto de tipos de función para controladores. Declarar una función mediante los tipos de función ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación a encontrar errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una función ProtocolUnbindAdapterEx denominada "MyUnbindAdapterEx", use el tipo de PROTOCOL_UNBIND_ADAPTER_EX como se muestra en este ejemplo de código:

PROTOCOL_UNBIND_ADAPTER_EX MyUnbindAdapterEx;

A continuación, implemente la función de la siguiente manera:

_Use_decl_annotations_
NDIS_STATUS
 MyUnbindAdapterEx(
    NDIS_HANDLE  UnbindContext,
    NDIS_HANDLE  ProtocolBindingContext
    )
  {...}

El tipo de función PROTOCOL_UNBIND_ADAPTER_EX se define en el archivo de encabezado Ndis.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función PROTOCOL_UNBIND_ADAPTER_EX en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante tipos de roles de función para controladores NDIS.

Para obtener información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Compatible con NDIS 6.0 y versiones posteriores.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	PASSIVE_LEVEL