EVT_SERCX_WAITMASK função de retorno de chamada (sercx.h)

Artigo
12/15/2024

A função de retorno de chamada de evento EvtSerCxWaitmask configura o controlador serial para monitorar os eventos em uma máscara de espera, que é um valor de máscara de bits que especifica um conjunto de eventos de hardware.

Sintaxe

EVT_SERCX_WAITMASK EvtSercxWaitmask;

NTSTATUS EvtSercxWaitmask(
  [in] WDFDEVICE Device
)
{...}

Parâmetros

[in] Device

Um identificador WDFDEVICE para o objeto de dispositivo da estrutura que representa o controlador serial.

Valor de retorno

A função EvtSerCxWaitmask retornará STATUS_SUCCESS se a chamada for bem-sucedida. Caso contrário, ele retornará um código de status de erro apropriado.

Observações

O driver do controlador serial implementa essa função de retorno de chamada. A extensão da estrutura serial (SerCx) chama essa função para notificar o driver quando a máscara de espera é alterada. Durante essa chamada, a função EvtSerCxWaitmask chama o método SerCxGetWaitMask para obter a nova máscara de espera. O driver imediatamente começa a monitorar os eventos na nova máscara de espera e descarta qualquer máscara de espera antiga que possa ter sido fornecida em uma chamada EvtSerCxWaitmask anterior. Se a nova máscara de espera for zero, o driver simplesmente descartará a máscara de espera antiga e deixará de monitorar os eventos de máscara de espera.

Quando o SerCx recebe uma solicitação IOCTL_SERIAL_SET_WAIT_MASK de um cliente, o manipulador de solicitações no SerCx chama a função EvtSerCxWaitmask para definir a nova máscara de espera. Para obter mais informações sobre os tipos de eventos que podem ser especificados por uma máscara de espera, consulte SERIAL_EV_XXX.

A função EvtSerCxWaitmask configura o hardware do controlador serial para monitorar os eventos na nova máscara de espera. Normalmente, a função permite interrupções para esses eventos. Depois de configurar o hardware, a função deve retornar imediatamente, sem esperar que um evento na máscara de espera ocorra.

Posteriormente, quando um evento na máscara de espera faz com que uma interrupção ocorra, o ISR no driver do controlador serial agenda uma função DPC a ser executada. Essa função DPC chama o método SerCxCompleteWait para notificar o SerCx do evento.

Inicialmente, depois que um cliente abre uma conexão com a porta serial e antes do primeiro chamada EvtSerCxWaitmask, a máscara de espera é efetivamente zero e o driver do controlador serial não está monitorando nenhum SERIAL_EV_eventos de XXX.

Para registrar uma função de retorno de chamada EvtSerCxWaitmask, o driver do controlador chama o método SerCxInitialize durante o EvtDriverDeviceAdd retorno de chamada.

Exemplos

O tipo de função para esse retorno de chamada é declarado em Sercx.h, da seguinte maneira.

typedef NTSTATUS
  EVT_SERCX_WAITMASK(
    __in WDFDEVICE Device
    );

Para definir uma função de retorno de chamada EvtSerCxWaitmask denominada MyEvtSerCxWaitmask, primeiro você deve fornecer uma declaração de função que SDV (Static Driver Verifier) e outras ferramentas de verificação exigem, da seguinte maneira.

EVT_SERCX_WAITMASK MyEvtSerCxWaitmask;

Em seguida, implemente a função de retorno de chamada da seguinte maneira.

NTSTATUS
  MyEvtSerCxWaitmask(
    __in WDFDEVICE Device
    )
{ ... }

Para obter mais informações sobre os requisitos de SDV para declarações de função, consulte Declarando funções usando tipos de função para drivers KMDF.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível a partir do Windows 8.
da Plataforma de Destino	Área de trabalho
cabeçalho	sercx.h
IRQL	Chamado no <DO IRQL = DISPATCH_LEVEL