MINIPORT_PAUSE função de retorno de chamada (ndis.h)

Artigo
08/07/2023

O NDIS chama a função MiniportPause de um driver de miniport para interromper o fluxo de dados de rede por meio de um adaptador de miniporto especificado.

Nota Você deve declarar a função usando o tipo MINIPORT_PAUSE . Para obter mais informações, consulte a seção Exemplos a seguir.

Sintaxe

MINIPORT_PAUSE MiniportPause;

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

Parâmetros

[in] MiniportAdapterContext

Um identificador para uma área de contexto que o driver de miniporto alocou em sua função MiniportInitializeEx . O driver de miniporta usa essa área de contexto para manter informações de estado para um adaptador de miniporta.

[in] PauseParameters

Um ponteiro para um NDIS_MINIPORT_PAUSE_PARAMETERS estrutura que define os parâmetros de pausa para o adaptador de miniporta.

Retornar valor

MiniportPause retorna um dos seguintes valores de status:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	O MiniportPause interrompeu com êxito o fluxo de dados de rede por meio do adaptador de miniport.
NDIS_STATUS_PENDING	O MiniportPause não concluiu a operação de pausa e a operação será concluída de forma assíncrona. O driver de miniporto deve chamar a função NdisMPauseComplete quando a operação for concluída.

Comentários

Um driver especifica o ponto de entrada MiniportPause quando ele chama o Função NdisMRegisterMiniportDriver .

O NDIS pausa um adaptador de miniporta para interromper o fluxo de dados que pode interferir em operações PnP, como adicionar ou remover um driver de filtro ou associar ou desassociar um driver de protocolo.

O NDIS chama a função MiniportPause de um driver de miniport para iniciar uma solicitação de pausa para o adaptador de miniporto especificado em MiniportAdapterContext. O adaptador de miniporta permanece no estado Pausando até que a operação de pausa seja concluída.

Para um adaptador de miniporta no estado Pausando , o driver de miniporta:

Aguarda todas as chamadas para o Função NdisMIndicateReceiveNetBufferLists a ser retornada.
Aguarda que o NDIS retorne a propriedade de todas as estruturas de NET_BUFFER_LIST de indicações de recebimento pendentes para o driver de miniporto Função MiniportReturnNetBufferLists .
Conclui todas as solicitações de envio pendentes e chama o Função NdisMSendNetBufferListsComplete para todas as solicitações de envio pendentes.
Rejeita todas as novas solicitações de envio feitas à sua MiniportSendNetBufferLists funciona imediatamente chamando NdisMSendNetBufferListsComplete. Ele deve definir a status completa em cada NET_BUFFER_LIST como NDIS_STATUS_PAUSED.
Pode fornecer status indicações com o Função NdisMIndicateStatusEx .
Deve lidar com solicitações OID na função MiniportOidRequest .
Não deve interromper completamente o adaptador de miniporta se parar o adaptador de miniporta impedir que o driver manifique solicitações ou forneça status indicações.
Não deve liberar os recursos alocados pelo driver durante a inicialização.

O NDIS não inicia outras operações PnP para o adaptador de miniporto, como interrupção, inicialização, alteração de energia, pausa ou solicitações de reinicialização, enquanto o adaptador de miniporto está no estado Pausando . O NDIS pode iniciar essas operações PnP depois que um adaptador de miniporto estiver no estado Pausado .

Depois que um driver de miniporta concluir todas as solicitações de envio pendentes e o NDIS retornar todas as estruturas de dados de rede recebidas (de indicações de recebimento pendentes), o driver deverá concluir a operação de pausa. Se o driver retornar NDIS_STATUS_SUCCESS do MiniportPause, a operação de pausa será concluída. Se o driver retornar NDIS_STATUS_PENDING, o adaptador de miniporto poderá permanecer no estado Pausando e a operação de pausa for concluída depois que o driver chamar a função NdisMPauseComplete . Depois que a operação de pausa for concluída, o adaptador de miniporto estará no estado Pausado .

Para um adaptador de miniporta no estado Pausado , o driver de miniporta:

Deve rejeitar todas as solicitações de envio feitas ao MiniportSendNetBufferLists imediatamente chamando NdisMSendNetBufferListsComplete. Ele deve definir o membro Status em cada NET_BUFFER_LIST como NDIS_STATUS_PAUSED.
Pode lidar com interrupções de recebimento (consulte a função MiniportInterrupt ) e interromper DPCs (consulte a função MiniportInterruptDPC ), mas não deve indicar dados de rede recebidos.
Pode fornecer status indicações com a função NdisMIndicateStatusEx.
Deve lidar com solicitações OID na função MiniportOidRequest .
Deve manipular solicitações para alterar o estado de energia do dispositivo no Função MiniportDevicePnPEventNotify .
Pode lidar com chamadas para funções NetTimerCallback .
Pode manipular solicitações para redefinir o hardware na função MiniportResetEx .

Os drivers de miniporta não podem falhar em uma solicitação de pausa. Portanto, se um driver de miniporto exigir recursos para lidar com uma solicitação de pausa, ele deverá pré-alocar os recursos durante a inicialização.

O NDIS chama a função MiniportRestart para iniciar uma solicitação de reinicialização para um adaptador de miniport que está pausado.

O NDIS chama MiniportPause em IRQL = PASSIVE_LEVEL.

Exemplos

Para definir uma função MiniportPause , primeiro você deve fornecer uma declaração de função que identifique o tipo de função que você está definindo. O Windows fornece um conjunto de tipos de função para drivers. Declarar uma função usando os tipos de função ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para escrever drivers para o sistema operacional Windows.

Por exemplo, para definir uma função MiniportPause chamada "MyPause", use o tipo MINIPORT_PAUSE conforme mostrado neste exemplo de código:

MINIPORT_PAUSE MyPause;

Em seguida, implemente sua função da seguinte maneira:

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

O tipo de função MINIPORT_PAUSE é definido no arquivo de cabeçalho Ndis.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função MINIPORT_PAUSE no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers NDIS.

Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Com suporte no NDIS 6.0 e posterior.
Plataforma de Destino	Windows
Cabeçalho	ndis.h (inclua Ndis.h)
IRQL	PASSIVE_LEVEL