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 da 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 da 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 solicitação de
[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 solicitação de
Valor de retorno
A função EvtSerCx2Control retorna 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 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 da estrutura para o controlador serial.
A função EvtSerCx2Control
Quando o SerCx2 recebe uma solicitação de controle de E/S serial que pode ser tratada apenas 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 o suporte para uma solicitação de controle de E/S específica deve concluir essa solicitação de controle de E/S com o código de status de erro STATUS_NOT_SUPPORTED.
Para concluir a solicitação de controle de E/S, o driver normalmente chama o método
O valor retornado da função EvtSerCx2Control sempre deve corresponder ao valor de status que essa função grava no bloco de status da solicitação de controle de E/S. A implementação atual do SerCx2 ignora esse valor retornado.
O 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 | Necessário |
| IOCTL_SERIAL_GET_BAUD_RATE | Necessário |
| IOCTL_SERIAL_GET_COMMSTATUS | Necessário |
| IOCTL_SERIAL_GET_DTRRTS | Necessário |
| IOCTL_SERIAL_GET_HANDFLOW | Necessário |
| IOCTL_SERIAL_GET_LINE_CONTROL | Necessário |
| IOCTL_SERIAL_GET_MODEM_CONTROL | Necessário |
| IOCTL_SERIAL_GET_MODEMSTATUS | Necessário |
| IOCTL_SERIAL_GET_PROPERTIES | Necessário |
| IOCTL_SERIAL_SET_BAUD_RATE | Necessário |
| IOCTL_SERIAL_SET_BREAK_OFF | Necessário |
| IOCTL_SERIAL_SET_BREAK_ON | Necessário |
| IOCTL_SERIAL_SET_DTR | Opcional |
| IOCTL_SERIAL_SET_FIFO_CONTROL | Opcional |
| IOCTL_SERIAL_SET_HANDFLOW | Necessário |
| IOCTL_SERIAL_SET_LINE_CONTROL | Necessário |
| IOCTL_SERIAL_SET_MODEM_CONTROL | Necessário |
| IOCTL_SERIAL_SET_RTS | Necessário |
A tabela anterior lista todos os IOCTLs serial que o SerCx2 apresenta à função EvtSerCx2Control
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 de 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
- erros
- holdReasons
IOCTL_SERIAL_GET_PROPERTIES
A função EvtSerCx2Control
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 valor de registro de status de modem bruto lido do hardware do controlador serial.
IOCTL_SERIAL_GET_HANDFLOW e IOCTL_SERIAL_SET_HANDFLOW
A função EvtSerCx2Control
O driver deve dar suporte ao seguinte bit de sinalizador no membro do
- SERIAL_CTS_HANDSHAKE
O driver deve dar suporte aos seguintes bits de sinalizador no membro
- SERIAL_RTS_CONTROL
- SERIAL_RTS_HANDSHAKE
Um driver que não dá suporte a um bit de sinalizador específico no ControlHandShake ou membro 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 ControlHandshake ou FlowReplace bit que 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 necessário, 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
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 encontram erros e é um requisito para gravar drivers para o sistema operacional Windows.
Por exemplo, para definir uma função de retorno de chamada EvtSerCx2Control denominada MyControl, use o tipo de função EVT_SERCX2_CONTROL, conforme mostrado neste exemplo de código:
EVT_SERCX2_CONTROL MyControl;
Em seguida, implemente sua 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 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 |
|---|---|
| de cliente com suporte mínimo | Disponível a partir do Windows 8.1. |
| da Plataforma de Destino |
Área de trabalho |
| cabeçalho | sercx.h |
| IRQL | Chamado no <DO IRQL = DISPATCH_LEVEL. |