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

Artigo
12/16/2024

A função de retorno de chamada de evento EvtSerCxPurge é chamada pela extensão da estrutura serial (SerCx) para limpar os buffers de hardware do controlador serial.

Sintaxe

EVT_SERCX_PURGE EvtSercxPurge;

NTSTATUS EvtSercxPurge(
  [in] WDFDEVICE Device,
  [in] ULONG PurgeMask
)
{...}

Parâmetros

[in] Device

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

[in] PurgeMask

Um conjunto de sinalizadores que descrevem os buffers de hardware que devem ser limpos. Atualmente, nenhum sinalizador é definido para operações de limpeza executadas pelo controlador serial. Para obter mais informações, consulte Comentários.

Valor de retorno

A função EvtSerCxPurge 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. O SerCx chama essa função quando um cliente (driver de aplicativo ou periférico) envia uma solicitação de controle IOCTL_SERIAL_PURGE que exige que os buffers de hardware gerenciados pelo controlador serial sejam limpos.

O SerCx executa as operações de limpeza designadas pelos sinalizadores listados na tabela a seguir.

Bit de sinalizador	Significado
SERIAL_PURGE_RXABORT	Limpe todas as solicitações de leitura.
SERIAL_PURGE_RXCLEAR	Limpe o buffer de entrada, se houver um. Todos os dados de recebimento neste buffer são descartados.
SERIAL_PURGE_TXABORT	Limpe todas as solicitações de gravação.
SERIAL_PURGE_TXCLEAR	Limpe o buffer de saída, se houver. Todos os dados de transmissão neste buffer são descartados.

A função EvtSerCxPurge nunca receberá uma solicitação de limpeza que contenha nenhum dos sinalizadores nesta tabela. Os sinalizadores SERIAL_PURGE_XXX são definidos no arquivo de cabeçalho Ntddser.h.

Atualmente, nenhum SERIAL_PURGE_sinalizadores de XXX são definidos para designar operações de limpeza executadas pelo driver do controlador serial e o driver do controlador serial não deve executar nenhuma operação de limpeza em resposta a uma chamada EvtSerCxPurge.

Se a solicitação de controle IOCTL_SERIAL_PURGE exigir que solicitações pendentes de leitura ou gravação sejam canceladas, o SerCx cancelará essas solicitações antes de chamar a função EvtSerCxPurge.

Para registrar uma função de retorno de chamada EvtSerCxPurge, 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_PURGE(
    __in WDFDEVICE Device,
    __in ULONG PurgeMask
    );

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

EVT_SERCX_PURGE MyEvtSerCxPurge;

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

NTSTATUS
  MyEvtSerCxPurge(
    __in WDFDEVICE Device,
    __in ULONG PurgeMask
    )
{ ... }

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

Consulte também

EvtDriverDeviceAdd

IOCTL_SERIAL_PURGE

SerCxInitialize

Compartilhar via