EVT_SERCX2_CONTROL função de retorno de chamada (sercx.h)
A função de retorno de chamada de evento EvtSerCx2Control é chamada pela versão 2 da extensão de estrutura serial (SerCx2) para lidar com uma solicitação de controle de E/S serial.
Sintaxe
EVT_SERCX2_CONTROL EvtSercx2Control;
NTSTATUS EvtSercx2Control(
[in] WDFDEVICE Device,
[in] WDFREQUEST Request,
[in] size_t OutputBufferLength,
[in] size_t InputBufferLength,
[in] ULONG IoControlCode
)
{...}
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 de controle de E/S serial.
[in] OutputBufferLength
O comprimento, em bytes, do buffer de saída para a solicitação de controle de E/S serial especificada pelo parâmetro Request .
[in] InputBufferLength
O comprimento, em bytes, do buffer de entrada para a solicitação de controle de E/S serial especificada pelo parâmetro Request .
[in] IoControlCode
Especifica o IOCTL (código de controle de E/S) da solicitação de controle de E/S serial especificada pelo parâmetro Request . As IOCTLs para solicitações de controle de E/S serial são definidas no arquivo de cabeçalho Ntddser.h. Para obter mais informações, consulte Comentários.
Retornar valor
A função EvtSerCx2Control retornará STATUS_SUCCESS se a chamada for bem-sucedida. Caso contrário, ele retornará um erro apropriado status código.
Comentários
O driver do controlador serial deve implementar essa função. 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.
A função EvtSerCx2Control permite que o driver manipule determinadas solicitações de controle de E/S serial que o SerCx2 não pode manipular. O SerCx2 manipula todo o processamento de um subconjunto das IOCTLs serial definidas no arquivo de cabeçalho Ntddser.h. No entanto, o SerCx2 depende do driver para lidar com solicitações de controle de E/S serial para executar operações dependentes de hardware.
Quando o SerCx2 recebe uma solicitação de controle de E/S serial que só pode ser manipulada pelo driver do controlador serial, o SerCx2 chama a função EvtSerCx2Control para entregar a solicitação de controle de E/S ao driver. O driver é responsável por concluir essa solicitação. Um driver que não implementa suporte para uma solicitação de controle de E/S específica deve concluir essa solicitação de controle de E/S com o erro STATUS_NOT_SUPPORTED status código.
Para concluir a solicitação de controle de E/S, o driver normalmente chama o método WdfRequestComplete e fornece, como parâmetros de entrada, o valor do parâmetro Request e um valor de status para indicar se a solicitação foi bem-sucedida. Esse valor status é gravado no bloco status da solicitação.
O valor retornado da função EvtSerCx2Control sempre deve corresponder ao valor status que essa função grava no bloco status da solicitação de controle de E/S. A implementação atual do SerCx2 ignora esse valor retornado.
SerCx2 chama a função EvtSerCx2Control para lidar com os IOCTLs mostrados na tabela a seguir. A coluna no lado direito da tabela indica se a função EvtSerCx2Control é necessária para implementar o suporte para um IOCTL específico.
| Nome da solicitação de controle de E/S | Obrigatório ou opcional |
|---|---|
| IOCTL_SERIAL_CLR_DTR | Opcional |
| IOCTL_SERIAL_CLR_RTS | Obrigatório |
| IOCTL_SERIAL_GET_BAUD_RATE | Obrigatório |
| IOCTL_SERIAL_GET_COMMSTATUS | Obrigatório |
| IOCTL_SERIAL_GET_DTRRTS | Obrigatório |
| IOCTL_SERIAL_GET_HANDFLOW | Obrigatório |
| IOCTL_SERIAL_GET_LINE_CONTROL | Obrigatório |
| IOCTL_SERIAL_GET_MODEM_CONTROL | Obrigatório |
| IOCTL_SERIAL_GET_MODEMSTATUS | Obrigatório |
| IOCTL_SERIAL_GET_PROPERTIES | Obrigatório |
| IOCTL_SERIAL_SET_BAUD_RATE | Obrigatório |
| IOCTL_SERIAL_SET_BREAK_OFF | Obrigatório |
| IOCTL_SERIAL_SET_BREAK_ON | Obrigatório |
| IOCTL_SERIAL_SET_DTR | Opcional |
| IOCTL_SERIAL_SET_FIFO_CONTROL | Opcional |
| IOCTL_SERIAL_SET_HANDFLOW | Obrigatório |
| IOCTL_SERIAL_SET_LINE_CONTROL | Obrigatório |
| IOCTL_SERIAL_SET_MODEM_CONTROL | Obrigatório |
| IOCTL_SERIAL_SET_RTS | Obrigatório |
A tabela anterior lista todos os IOCTLs serial que o SerCx2 apresenta para a função EvtSerCx2Control . Para qualquer IOCTL que não esteja nesta lista, o SerCx2 manipula o IOCTL ou falha imediatamente no IOCTL e define a solicitação status como STATUS_NOT_SUPPORTED. O SerCx2 manipula IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION solicitações, mas chama a função de retorno de chamada de evento EvtSerCx2ApplyConfig durante o processamento dessa solicitação. O SerCx2 manipula IOCTL_SERIAL_PURGE solicitações, mas pode chamar a função de retorno de chamada de evento EvtSerCx2PurgeFifos durante o processamento de tal solicitação. O SerCx faz o processamento preliminar de solicitações de IOCTL_SERIAL_SET_WAIT_MASK , mas chama a função de retorno de chamada de evento EvtSerCx2SetWaitMask , se ela for implementada, para concluir o tratamento de tal solicitação. Para obter mais informações sobre o suporte do SerCx2 para IOCTLs serial, consulte Interface de solicitação de E/S serial.
IOCTL_SERIAL_CLR_DTR e IOCTL_SERIAL_SET_DTR
Se a função EvtSerCx2Control no driver do controlador serial der suporte à solicitação IOCTL_SERIAL_SET_DTR , essa função também deverá dar suporte à solicitação IOCTL_SERIAL_CLR_DTR e vice-versa. Se o driver não der suporte a essas duas solicitações, o manipulador do driver para a solicitação IOCTL_SERIAL_GET_DTRRTS deverá definir o bit de sinalizador SERIAL_DTR_STATE no valor de saída dessa solicitação como zero.
IOCTL_SERIAL_GET_DTRRTS
A função EvtSerCx2Control no driver do controlador serial deve dar suporte à solicitação IOCTL_SERIAL_GET_DTRRTS , mas o manipulador do driver para essa solicitação é necessário para dar suporte apenas ao bit de sinalizador SERIAL_RTS_STATE no valor de saída dessa solicitação. Como opção, o driver também pode dar suporte ao bit de sinalizador SERIAL_DTR_STATE. Se não houver suporte para o bit de sinalizador SERIAL_DTR_STATE, defina esse bit como zero.
IOCTL_SERIAL_GET_COMMSTATUS
A função EvtSerCx2Control no driver do controlador serial deve dar suporte à solicitação IOCTL_SERIAL_GET_COMMSTATUS , mas o manipulador do driver para essa solicitação é necessário para dar suporte apenas aos seguintes membros da estrutura de SERIAL_STATUS usada por esta solicitação:
- Erros
- HoldReasons
IOCTL_SERIAL_GET_PROPERTIES
A função EvtSerCx2Control no driver do controlador serial deve dar suporte à solicitação IOCTL_SERIAL_GET_PROPERTIES . O manipulador do driver para essa solicitação deve definir o membro MaxBaud da estrutura de SERIAL_COMMPROP usada por essa solicitação para a taxa máxima de baud com suporte, expressa em bits por segundo (bps). Por exemplo, se o controlador serial der suporte a uma taxa máxima de baud de 115.200 bps, o driver definirá MaxBaud = 115200.
IOCTL_SERIAL_GET_MODEMSTATUS
A função EvtSerCx2Control no driver do controlador serial deve dar suporte à solicitação de IOCTL_SERIAL_GET_MODEMSTATUS . O manipulador do driver para essa solicitação deve definir o valor de saída da solicitação como o modem bruto status registrar o valor lido do hardware do controlador serial.
IOCTL_SERIAL_GET_HANDFLOW e IOCTL_SERIAL_SET_HANDFLOW
A função EvtSerCx2Control no driver do controlador serial deve dar suporte às solicitações IOCTL_SERIAL_GET_HANDFLOW e IOCTL_SERIAL_SET_HANDFLOW , mas é necessária para dar suporte apenas a um subconjunto dos bits de sinalizador definidos para essas solicitações. Os bits de sinalizador são definidos para os membros ControlHandShake e FlowReplace da estrutura SERIAL_HANDFLOW usada por essas solicitações.
O driver deve dar suporte ao seguinte bit de sinalizador no membro ControlHandshake :
- SERIAL_CTS_HANDSHAKE
O driver deve dar suporte aos seguintes bits de sinalizador no membro FlowReplace :
- SERIAL_RTS_CONTROL
- SERIAL_RTS_HANDSHAKE
Um driver que não dá suporte a um bit de sinalizador específico no membro ControlHandShake ou FlowReplace deve definir esse bit de sinalizador como zero no valor de saída da solicitação IOCTL_SERIAL_GET_HANDFLOW . Se uma solicitação IOCTL_SERIAL_SET_HANDFLOW especificar um bit de sinalizador ControlHandshake ou FlowReplace ao qual o driver não dá suporte, a função EvtSerCx2Control deverá falhar na solicitação e retornar STATUS_INVALID_PARAMETER.
Como opção, um driver pode dar suporte aos membros XonLimit e XoffLimit da estrutura SERIAL_HANDFLOW . No entanto, esses membros raramente são, se nunca, necessários, e a Microsoft recomenda não dar suporte a eles. Um driver que não dá suporte aos membros XonLimit e XoffLimit deve definir esses membros como zero no valor de saída da solicitação de IOCTL_SERIAL_GET_HANDFLOW . Se uma solicitação IOCTL_SERIAL_SET_HANDFLOW especificar um membro XonLimit ou XoffLimit diferente de zero e o driver não oferecer suporte a esses membros, a função EvtSerCx2Control deverá falhar na solicitação e retornar STATUS_NOT_IMPLEMENTED.
Exemplos
Para definir uma função de retorno de chamada EvtSerCx2Control , 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 escrever drivers para o sistema operacional Windows.
Por exemplo, para definir uma função de retorno de chamada EvtSerCx2Control chamada MyControl, use o tipo de função EVT_SERCX2_CONTROL , conforme mostrado neste exemplo de código:
EVT_SERCX2_CONTROL MyControl;
Em seguida, implemente a função de retorno de chamada da seguinte maneira:
_Use_decl_annotations_
NTSTATUS
MyControl(
WDFDEVICE Device,
WDFREQUEST Request,
size_t OutputBufferLength,
size_t InputBufferLength,
ULONG IoControlCode
)
{...}
O tipo de função EVT_SERCX2_CONTROL é 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_CONTROL 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 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