EVT_SERCX2_SET_WAIT_MASK função de retorno de chamada (sercx.h)
A função de retorno de chamada de evento EvtSerCx2SetWaitMask é chamada pela versão 2 da extensão de estrutura serial (SerCx2) para configurar o controlador serial para monitorar um conjunto de eventos de hardware especificados por uma máscara de espera.
Sintaxe
EVT_SERCX2_SET_WAIT_MASK EvtSercx2SetWaitMask;
void EvtSercx2SetWaitMask(
[in] WDFDEVICE Device,
[in] WDFREQUEST Request,
[in] ULONG WaitMask
)
{...}
Parâmetros
[in] Device
Um identificador WDFDEVICE para o objeto de dispositivo de estrutura que representa o controlador serial. O driver do controlador serial criou esse objeto em sua função de retorno de chamada EvtDriverDeviceAdd . Para obter mais informações, consulte SerCx2InitializeDevice.
[in] Request
Um identificador WDFREQUEST para o objeto de solicitação de estrutura que representa a solicitação IOCTL_SERIAL_SET_WAIT_MASK .
[in] WaitMask
A nova máscara de espera. Para obter mais informações, consulte Comentários.
Retornar valor
Nenhum
Comentários
O driver do controlador serial pode, como opção, implementar essa função. Se implementado, o driver registra a função na chamada para o método SerCx2InitializeDevice que conclui a inicialização do objeto de dispositivo de estrutura para o controlador serial.
Quando o SerCx recebe uma solicitação IOCTL_SERIAL_SET_WAIT_MASK de um cliente, o manipulador de solicitação em SerCx2 chama a função EvtSerCx2SetWaitMask , se ela for implementada, para notificar o driver de que a máscara de espera foi alterada. Se a máscara de espera não for zero, o driver começará imediatamente a monitorar os eventos na nova máscara de espera e descartará qualquer máscara de espera antiga que possa ter sido fornecida em uma chamada EvtSerCx2SetWaitMask anterior. Se a nova máscara de espera for zero, o driver simplesmente descartará a máscara de espera antiga e deixará de monitorar quaisquer eventos de 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.
Se o driver não implementar essa função, o SerCx2 falhará em todas as solicitações de IOCTL_SERIAL_SET_WAIT_MASK com erro status código STATUS_NOT_SUPPORTED.
Para monitorar os eventos na máscara de espera, a função EvtSerCx2SetWaitMask normalmente permite interrupções para esses eventos. Posteriormente, quando um evento na máscara de espera é detectado, o driver do controlador serial chama o método SerCx2CompleteWait para notificar o SerCx2 do evento.
A função EvtSerCx2SetWaitMask é responsável por concluir a solicitação IOCTL_SERIAL_SET_WAIT_MASK apontada pelo parâmetro Request . Depois que o driver do controlador serial habilitar as interrupções necessárias, ele chama o método WdfRequestComplete e fornece, como parâmetros de entrada, o valor do parâmetro Request e um valor status para indicar se a solicitação foi bem-sucedida.
Antes que o driver do controlador serial chame WdfRequestComplete para concluir a solicitação, o driver deve concluir todas as chamadas para SerCx2CompleteWait que ainda possam estar pendentes devido a eventos na máscara de espera antiga.
Inicialmente, depois que um cliente abre uma conexão lógica com a porta serial e antes da primeira chamada EvtSerCx2SetWaitMask , a máscara de espera é efetivamente zero e o driver do controlador serial não está monitorando nenhum SERIAL_EV_XXX eventos.
O SerCx2 falha em uma solicitação de IOCTL_SERIAL_SET_WAIT_MASK que tem uma máscara de espera que inclui qualquer um dos seguintes sinalizadores de evento SERIAL_EV_XXX:
- SERIAL_EV_PERR
- SERIAL_EV_RING
- SERIAL_EV_RXFLAG
Se implementada, a função EvtSerCx2SetWaitMask deverá dar suporte aos seguintes sinalizadores de evento:
- SERIAL_EV_CTS
- SERIAL_EV_BREAK
- SERIAL_EV_ERR
Exemplos
Para definir uma função de retorno de chamada EvtSerCx2SetWaitMask , primeiro você deve fornecer uma declaração de função que identifique o tipo de função de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada 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 gravar drivers para o sistema operacional Windows.
Por exemplo, para definir uma função de retorno de chamada EvtSerCx2SetWaitMask chamada MySetWaitmask, use o tipo de função EVT_SERCX2_SET_WAIT_MASK , conforme mostrado neste exemplo de código:
EVT_SERCX2_SET_WAIT_MASK MySetWaitmask;
Em seguida, implemente a função de retorno de chamada da seguinte maneira:
_Use_decl_annotations_
VOID
MySetWaitmask(
WDFDEVICE Device,
WDFREQUEST Request,
ULONG WaitMask
)
{...}
O tipo de função EVT_SERCX2_SET_WAIT_MASK é definido no arquivo de cabeçalho Sercx.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 EVT_SERCX2_SET_WAIT_MASK 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 KMDF. Para obter mais informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível a partir do Windows 8.1. |
| Plataforma de Destino | Área de Trabalho |
| Cabeçalho | sercx.h |
| IRQL | Chamado em IRQL <= DISPATCH_LEVEL. |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de