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

Artículo
02/29/2024

NDIS llama a la función FilterAttach del controlador de filtro para asignar e inicializar las estructuras de datos de un módulo de filtro.

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

Sintaxis

FILTER_ATTACH FilterAttach;

NDIS_STATUS FilterAttach(
  [in] NDIS_HANDLE NdisFilterHandle,
  [in] NDIS_HANDLE FilterDriverContext,
  [in] PNDIS_FILTER_ATTACH_PARAMETERS AttachParameters
)
{...}

Parámetros

[in] NdisFilterHandle

Identificador NDIS que identifica un módulo de filtro. El controlador de filtro debe guardar este identificador. El identificador es necesario en las llamadas posteriores a las funciones NdisFXxx .

[in] FilterDriverContext

Identificador que el controlador pasó a . Función NdisFRegisterFilterDriver que identifica el área de contexto del controlador.

[in] AttachParameters

Puntero a un NDIS_FILTER_ATTACH_PARAMETERS estructura que define los parámetros de inicialización para el módulo de filtro.

Valor devuelto

FilterAttach devuelve uno de los siguientes valores de estado:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	FilterAttach asignó e inicializó correctamente estructuras de datos para este módulo de filtro.
NDIS_STATUS_RESOURCES	Error de FilterAttach debido a recursos insuficientes.
NDIS_STATUS_FAILURE	FilterAttach devuelve NDIS_STATUS_FAILURE si no se aplica ninguno de los valores anteriores. El controlador de filtro debe llamar a la función NdisWriteEventLogEntry junto con parámetros que especifican el motivo del error.

Comentarios

FilterAttach es una función necesaria. NDIS llama a la función FilterAttach del controlador de filtro cuando el módulo de filtro especificado está en estado Desasociado . NDIS puede llamar a FilterAttach en cualquier momento después de que se devuelva la llamada a la función FilterSetOptions .

Al principio de la ejecución en FilterAttach, el módulo de filtro entra en el estado Attaching (Adjuntar ).

Los controladores de filtro deben evitar emitir consultas OID innecesarias. En su lugar, use la información de . NDIS_FILTER_ATTACH_PARAMETERS, cuando esté disponible, para obtener información sobre los controladores subyacentes.

Un controlador de filtro realiza las siguientes operaciones cuando NDIS llama a FilterAttach.

Crea un área de contexto para el módulo de filtro y asigna grupos de búferes y cualquier otro recurso.
Llama a la función NdisFSetAttributes junto con el NdisFilterHandle que NDIS pasó a FilterAttach. El parámetro FilterModuleContext de NdisFSetAttributes especifica el área de contexto del controlador de filtro para este módulo de filtro. NDIS pasa este área de contexto a las funciones FilterXxx del controlador de filtro.
Opcionalmente, lee los parámetros de configuración del Registro.
Si las operaciones anteriores se completaron correctamente, el módulo de filtro entra en estado Pausado .
Si se produjo un error en las operaciones anteriores, el controlador de filtro debe liberar los recursos asignados en la función FilterAttach y devolver el módulo de filtro al estado Desasociado .
Devuelve NDIS_STATUS_SUCCESS o un código de error adecuado.

Un controlador de filtro no debe realizar solicitudes de envío, indicar los datos recibidos, realizar solicitudes de OID o realizar indicaciones de estado del estado de conexión .

NDIS llama a la función FilterDetach de un controlador de filtro para liberar todos los recursos asociados a un módulo de filtro y devolver el módulo de filtro al estado Desasociado .

NDIS llama a FilterAttach en IRQL = PASSIVE_LEVEL.

Ejemplos

Para definir una función FilterAttach , primero debe proporcionar una declaración de función que identifique el tipo de función que va a definir. 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 FilterAttach denominada "MyAttach", use el tipo FILTER_ATTACH como se muestra en este ejemplo de código:

FILTER_ATTACH MyAttach;

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

_Use_decl_annotations_
NDIS_STATUS
 MyAttach(
    NDIS_HANDLE  NdisFilterHandle,
    NDIS_HANDLE  FilterDriverContext,
    PNDIS_FILTER_ATTACH_PARAMETERS  AttachParameters
    )
  {...}

El tipo de función FILTER_ATTACH 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 FILTER_ATTACH en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, consulte Declaración de funciones mediante el uso de 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	Se admite en NDIS 6.0 y versiones posteriores.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	PASSIVE_LEVEL