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

Artículo
08/07/2023

La función FilterRestart inicia una operación de reinicio para el módulo de filtro especificado.

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

Sintaxis

FILTER_RESTART FilterRestart;

NDIS_STATUS FilterRestart(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_RESTART_PARAMETERS RestartParameters
)
{...}

Parámetros

[in] FilterModuleContext

Identificador del área de contexto del módulo de filtro que debe reiniciar el controlador de filtro. El controlador de filtro creó e inicializó este área de contexto en la función FilterAttach .

[in] RestartParameters

Puntero a un NDIS_FILTER_RESTART_PARAMETERS estructura que define los parámetros de reinicio para el módulo de filtro.

Valor devuelto

FilterRestart devuelve uno de los siguientes valores de estado:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	FilterRestart reinició correctamente el módulo de filtro especificado.
NDIS_STATUS_PENDING	El controlador de filtro completará la solicitud de forma asincrónica con una llamada a la función NdisFRestartComplete después de completar la operación de reinicio.
NDIS_STATUS_RESOURCES	Error de FilterRestart debido a recursos insuficientes.
NDIS_STATUS_FAILURE	No se aplica ninguno de los valores de estado anteriores. El controlador de filtro debe llamar a la función NdisWriteEventLogEntry junto con parámetros que especifican el motivo del error.

Comentarios

FilterRestart es una función necesaria para los controladores de filtro. NDIS puede llamar a FilterRestart cuando un módulo de filtro está en estado Pausado . El módulo de filtro entra en el estado reinicio al principio de la ejecución de FilterRestart.

Cuando NDIS llama a FilterRestart, un controlador de filtro:

Debe completar las operaciones necesarias para reiniciar las operaciones normales de envío y recepción.
Opcionalmente, lee o escribe parámetros de configuración.
Opcionalmente, reasigna los grupos de búferes.
Opcionalmente, modifica los atributos de reinicio especificados en el miembro RestartAttributes del objeto NDIS_FILTER_RESTART_PARAMETERS estructura. Si el puntero de RestartAttributes es NULL, el controlador de filtro no debe modificar ni agregar a la lista de atributos de reinicio. Si el puntero de RestartAttributes no es NULL, apunta a la primera estructura NDIS_RESTART_ATTRIBUTES de la lista de atributos de reinicio. Si un controlador de filtro no se reinicia, no debe modificar ningún atributo.
Opcionalmente, usa solicitudes de OID para consultar o establecer información en los controladores subyacentes. Los controladores de filtro no deben emitir solicitudes de OID para obtener información que ya se proporciona en la lista de atributos de reinicio.
Devuelve NDIS_STATUS_SUCCESS o un estado de error.

Si un controlador de filtro modifica la lista de atributos de reinicio, el controlador de filtro:

No debe modificar ningún atributo específico del medio si no reconoce el OID en el miembro Oid del NDIS_RESTART_ATTRIBUTES estructura.
Puede agregar nuevos atributos específicos de medios a la lista de atributos de reinicio. En esta situación, el controlador de filtro debe asignar una nueva estructura de NDIS_RESTART_ATTRIBUTES, por ejemplo, con . Función NdisAllocateMemoryWithTagPriority y proporcionan espacio de memoria para los nuevos atributos. Después de propagar los atributos de reinicio a controladores demasiado excesivos, NDIS libera la memoria de atributos para los controladores de filtro.
Puede modificar los atributos específicos de los medios en la lista de atributos de reinicio. Si el controlador de filtro requiere más espacio de memoria, puede liberar la estructura NDIS_RESTART_ATTRIBUTES con la función NdisFreeMemory y asignar una nueva estructura para contener la información modificada. Después de propagar los atributos de reinicio a controladores demasiado excesivos, NDIS libera la memoria de atributos para los controladores de filtro.
Debe, si el miembro Oid de la estructura NDIS_RESTART_ATTRIBUTES es OID_GEN_MINIPORT_RESTART_ATTRIBUTES, asegúrese de que NDIS_RESTART_GENERAL_ATTRIBUTES estructura contiene la información que requiere el controlador de filtro. Para asegurarse de que la estructura de NDIS_RESTART_GENERAL_ATTRIBUTES contiene la información necesaria, debe comprobar el miembro Revision en la estructura NDIS_OBJECT_HEADER especificada en el miembro Header de la estructura NDIS_RESTART_GENERAL_ATTRIBUTES.
Nota Un controlador de filtro puede modificar cualquier miembro de la estructura NDIS_RESTART_GENERAL_ATTRIBUTES. Si algunos atributos que el controlador de filtro debe modificar no se incluyen en la revisión de la estructura proporcionada por NDIS, el controlador de filtro debe confiar en controladores demasiado excesivos para emitir solicitudes de OID para los atributos que faltan. El controlador de filtro puede modificar los atributos cuando completa la solicitud de OID.
Debe, si el controlador de filtro cambia los atributos de reinicio, proporcione una función FilterOidRequest . El controlador de filtro debe asegurarse de que la información que reciben los controladores excesivamente en los atributos de reinicio es coherente con la información que reciben en respuesta a las solicitudes de OID.

Una vez que el controlador de filtro devuelve su estado o llama a la función NdisFRestartComplete , se completa la operación de reinicio. Si la operación se completó correctamente, el módulo de filtro se encuentra en estado En ejecución y se reanuda el procesamiento normal de envío y recepción. Si se produjo un error en la operación de reinicio, el módulo de filtro vuelve al estado Pausado .

NDIS llama a FilterRestart en IRQL = PASSIVE_LEVEL.

Ejemplos

Para definir una función FilterRestart , 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 FilterRestart denominada "MyRestart", use el tipo FILTER_RESTART como se muestra en este ejemplo de código:

FILTER_RESTART MyRestart;

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

_Use_decl_annotations_
NDIS_STATUS
 MyRestart(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_RESTART_PARAMETERS  FilterRestartParameters
    )
  {...}

El tipo de función FILTER_RESTART 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_RESTART 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