EVT_SERCX_APPLY_CONFIG função de retorno de chamada (sercx.h)
A função de retorno de chamada de evento EvtSerCxApplyConfig instrui o driver do controlador serial a aplicar uma lista de configurações ao hardware do controlador serial.
Sintaxe
EVT_SERCX_APPLY_CONFIG EvtSercxApplyConfig;
NTSTATUS EvtSercxApplyConfig(
[in] WDFDEVICE Device,
[in] PVOID ConnectionParameters
)
{...}
Parâmetros
[in] Device
Um identificador WDFDEVICE para o objeto de dispositivo de estrutura que representa o controlador serial.
[in] ConnectionParameters
Um ponteiro para a estrutura de parâmetros de conexão. Essa função deve converter esse parâmetro para o tipo de ponteiro apropriado, analisar a estrutura de dados para obter as configurações e aplicar essas configurações ao hardware do controlador serial. A estrutura de parâmetros de conexão é definida pelo fornecedor da plataforma de hardware e é opaca tanto para a extensão de estrutura serial (SerCx) quanto para o sistema operacional.
Retornar valor
A função EvtSerCxApplyConfig retornará STATUS_SUCCESS se a chamada for bem-sucedida. Caso contrário, ele retornará um erro apropriado status código.
Comentários
O SerCx chama essa função durante a inicialização do controlador serial para garantir que o hardware esteja em um estado inicial válido. Além disso, essa função é chamada sempre que um cliente envia uma solicitação de controle de E/ S IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION para o controlador.
O SerCx obtém esses parâmetros de configuração do descritor de recursos acpi para o dispositivo de controlador serial. O formato de dados que o firmware ACPI usa para armazenar essas configurações deve ser o mesmo formato de dados esperado pelo driver do controlador serial.
Quando um cliente envia uma solicitação de IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION para uma porta serial gerenciada pelo SerCx, o SerCx determina se o driver do controlador serial para a porta serial dá suporte ao retorno de chamada EvtSerCxApplyConfig e se o descritor de recursos acpi para a porta serial fornece configurações de conexão padrão. Caso contrário, o SerCx concluirá a solicitação com erro status STATUS_NOT_SUPPORTED de código. Caso contrário, o SerCx passará os parâmetros de conexão para a função de retorno de chamada EvtSerCxApplyConfig do driver. Depois que esse retorno de chamada retorna, o SerCx conclui a solicitação e usa o valor retornado do retorno de chamada como o código status para a solicitação.
Se um driver de controlador serial precisar obter os parâmetros de conexão padrão em um momento diferente de durante um retorno de chamada EvtSerCxApplyConfig , o driver poderá chamar o método SerCxGetConnectionParameters .
Para registrar uma função de retorno de chamada EvtSerCxApplyConfig , o driver deve chamar o método SerCxInitialize .
Exemplos
O tipo de função para esse retorno de chamada é declarado em Sercx.h, da seguinte maneira.
typedef NTSTATUS
EVT_SERCX_APPLY_CONFIG(
__in WDFDEVICE Device
);
Para definir uma função de retorno de chamada EvtSerCxApplyConfig chamada MyEvtSerCxApplyConfig
, primeiro você deve fornecer uma declaração de função que o SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação exigem, da seguinte maneira.
EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;
Em seguida, implemente a função de retorno de chamada da seguinte maneira.
NTSTATUS
MyEvtSerCxApplyConfig(
__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 de função para drivers KMDF.
O exemplo de código a seguir mostra uma implementação parcial de uma função EvtSerCxApplyConfig para um UART.//
// Define the UART ACPI descriptor, plus any vendor-specific
// data that is needed by the serial controller (UART) driver.
//
#define ANYSIZE_ARRAY 1
//
// Common resource name descriptor
//
typedef struct _PNP_IO_DESCRIPTOR_RESOURCE_NAME {
UCHAR ResourceIndex;
UCHAR ResourceName[ANYSIZE_ARRAY];
} PNP_IO_DESCRIPTOR_RESOURCE_NAME, *PPNP_IO_DESCRIPTOR_RESOURCE_NAME;
//
// Bus descriptor for a UART
//
typedef struct _PNP_UART_SERIAL_BUS_DESCRIPTOR {
PNP_SERIAL_BUS_DESCRIPTOR SerialBusDescriptor;
ULONG BaudRate;
USHORT RxBufferSize;
USHORT TxBufferSize;
UCHAR Parity;
// Include any optional vendor data here:
...
// Append the PNP_IO_DESCRIPTOR_RESOURCE_NAME here:
....
} PNP_UART_SERIAL_BUS_DESCRIPTOR, *PPNP_UART_SERIAL_BUS_DESCRIPTOR;
EVT_SERCX_APPLY_CONFIG UartEvtApplyConfig;
//
// Implementation of an EvtSerCxApplyConfig callback function
//
NTSTATUS
UartEvtApplyConfig(
__in WDFDEVICE Device,
__in PVOID ConnectionParameters
)
{
NTSTATUS status = STATUS_SUCCESS;
PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER connection;
PPNP_SERIAL_BUS_DESCRIPTOR descriptor;
PPNP_UART_SERIAL_BUS_DESCRIPTOR uartDescriptor;
if (ConnectionParameters == NULL)
{
status = STATUS_INVALID_PARAMETER;
}
if (NT_SUCCESS(status))
{
connection = (PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER)ConnectionParameters;
if (connection->PropertiesLength < sizeof(PNP_SERIAL_BUS_DESCRIPTOR))
{
status = STATUS_INVALID_PARAMETER;
}
}
if (NT_SUCCESS(status))
{
descriptor = (PPNP_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties;
if (descriptor->SerialBusType != UART_SERIAL_BUS_TYPE)
{
status = STATUS_INVALID_PARAMETER;
}
}
if (NT_SUCCESS(status))
{
uartDescriptor = (PPNP_UART_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties;
// Apply the configuration settings from
// the UART descriptor.
...
}
return status;
}
Os tipos de ponteiro PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER e PPNP_SERIAL_BUS_DESCRIPTOR no exemplo de código anterior são definidos no arquivo de cabeçalho Reshub.h.
Requisitos
Requisito | Valor |
---|---|
Cliente mínimo com suporte | Disponível a partir do Windows 8. |
Plataforma de Destino | Área de Trabalho |
Cabeçalho | sercx.h |
IRQL | Chamado em IRQL <= DISPATCH_LEVEL |
Confira também
Comentários
https://aka.ms/ContentUserFeedback.
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, consulteEnviar e exibir comentários de