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

Artículo
05/23/2024

NDIS llama a la función MiniportPause de un controlador de miniporte para detener el flujo de datos de red a través de un adaptador de miniporte especificado.

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

Sintaxis

MINIPORT_PAUSE MiniportPause;

NDIS_STATUS MiniportPause(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] PNDIS_MINIPORT_PAUSE_PARAMETERS PauseParameters
)
{...}

Parámetros

[in] MiniportAdapterContext

Identificador de un área de contexto que el controlador de minipuerto asignó en su función MiniportInitializeEx . El controlador de minipuerto usa este área de contexto para mantener la información de estado de un adaptador de minipuerto.

[in] PauseParameters

Puntero a un NDIS_MINIPORT_PAUSE_PARAMETERS estructura que define los parámetros de pausa para el adaptador de minipuerto.

Valor devuelto

MiniportPause devuelve uno de los siguientes valores de estado:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	MiniportPause detuvo correctamente el flujo de datos de red a través del adaptador de miniporte.
NDIS_STATUS_PENDING	MiniportPause no completó la operación de pausa y la operación se completará de forma asincrónica. El controlador de minipuerto debe llamar a la función NdisMPauseComplete cuando se complete la operación.

Comentarios

Un controlador especifica el punto de entrada MiniportPause cuando llama a . Función NdisMRegisterMiniportDriver .

NDIS pausa un adaptador de minipuerto para detener el flujo de datos que podría interferir con las operaciones PnP, como agregar o quitar un controlador de filtro, o enlazar o desenlazar un controlador de protocolo.

NDIS llama a la función MiniportPause de un controlador de miniporte para iniciar una solicitud de pausa para el adaptador de miniporte especificado en MiniportAdapterContext. El adaptador de minipuerto permanece en estado de pausa hasta que se completa la operación de pausa.

Para un adaptador de minipuerto en estado de pausa , el controlador de minipuerto:

Espera todas las llamadas a Función NdisMIndicateReceiveNetBufferLists que se va a devolver.
Espera a que NDIS devuelva la propiedad de todas las estructuras NET_BUFFER_LIST desde indicaciones de recepción pendientes al controlador de miniporte Función MiniportReturnNetBufferLists .
Completa todas las solicitudes de envío pendientes y llama a Función NdisMSendNetBufferListsComplete para todas las solicitudes de envío pendientes.
Rechaza todas las solicitudes de envío nuevas realizadas a su MiniportSendNetBufferLists funciona inmediatamente llamando a NdisMSendNetBufferListsComplete. Debe establecer el estado completo en cada NET_BUFFER_LIST en NDIS_STATUS_PAUSED.
Puede proporcionar indicaciones de estado con Función NdisMIndicateStatusEx .
Debe controlar las solicitudes de OID en la función MiniportOidRequest .
No debe detener el adaptador de miniporte por completo si detener el adaptador de minipuerto impide que el controlador controle las solicitudes o proporcione indicaciones de estado.
No debe liberar los recursos asignados por el controlador durante la inicialización.

NDIS no inicia otras operaciones PnP para el adaptador de minipuerto, como detener, inicializar, cambiar la energía, pausar o reiniciar solicitudes, mientras que el adaptador de minipuerto está en estado de pausa . NDIS puede iniciar estas operaciones PnP después de que un adaptador de minipuerto esté en estado Pausado .

Una vez que un controlador de miniporte completa todas las solicitudes de envío pendientes y NDIS devuelve todas las estructuras de datos de red recibidas (de indicaciones de recepción pendientes), el controlador debe completar la operación de pausa. Si el controlador devuelve NDIS_STATUS_SUCCESS desde MiniportPause, se completa la operación de pausa. Si el controlador devuelve NDIS_STATUS_PENDING, el adaptador de minipuerto puede permanecer en estado de pausa y la operación de pausa se completa después de que el controlador llame a la función NdisMPauseComplete . Una vez completada la operación de pausa, el adaptador de miniporte se encuentra en estado Pausado .

Para un adaptador de minipuerto en estado Pausado , el controlador de minipuerto:

Debe rechazar todas las solicitudes de envío realizadas a MiniportSendNetBufferLists inmediatamente llamando a NdisMSendNetBufferListsComplete. Debe establecer el miembro Status en cada NET_BUFFER_LIST en NDIS_STATUS_PAUSED.
Puede controlar las interrupciones de recepción (vea la función MiniportInterrupt ) e interrumpir los DPC (consulte la función MiniportInterruptDPC ), pero no debe indicar los datos de red recibidos.
Puede proporcionar indicaciones de estado con la función NdisMIndicateStatusEx .
Debe controlar las solicitudes de OID en la función MiniportOidRequest .
Debe controlar las solicitudes para cambiar el estado de alimentación del dispositivo en Función MiniportDevicePnPEventNotify .
Puede controlar las llamadas a las funciones NetTimerCallback .
Puede controlar las solicitudes para restablecer el hardware en la función MiniportResetEx .

Los controladores de minipuerto no pueden producir un error en una solicitud de pausa. Por lo tanto, si un controlador de minipuerto requiere recursos para controlar una solicitud de pausa, debe preasignar los recursos durante la inicialización.

NDIS llama a la función MiniportRestart para iniciar una solicitud de reinicio para un adaptador de miniporte que está en pausa.

NDIS llama a MiniportPause en IRQL = PASSIVE_LEVEL.

Ejemplos

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

MINIPORT_PAUSE MyPause;

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

_Use_decl_annotations_
NDIS_STATUS
 MyPause(
    NDIS_HANDLE  MiniportAdapterContext,
    PNDIS_MINIPORT_PAUSE_PARAMETERS  MiniportPauseParameters
    )
  {...}

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