Função SerCx2PioTransmitCreate (sercx.h)

Artigo
08/07/2023

O método SerCx2PioTransmitCreate cria um objeto pio-transmit, que a versão 2 da extensão de estrutura serial (SerCx2) usa para executar transações de transmissão de PIO.

Sintaxe

NTSTATUS SerCx2PioTransmitCreate(
  [in]           WDFDEVICE                   Device,
  [in]           PSERCX2_PIO_TRANSMIT_CONFIG PioTransmitConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES      Attributes,
  [out]          SERCX2PIOTRANSMIT           *PioTransmit
);

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] PioTransmitConfig

Um ponteiro para uma estrutura SERCX2_PIO_TRANSMIT_CONFIG . Antes de chamar esse método, o chamador deve chamar a função SERCX2_PIO_TRANSMIT_CONFIG_INIT para inicializar a estrutura. Essa estrutura contém ponteiros para um conjunto de rotinas de retorno de chamada de evento implementadas pelo driver do controlador serial. O SerCx2 chama essas funções para executar transações de transmissão de PIO.

[in, optional] Attributes

Um ponteiro para uma estrutura WDF_OBJECT_ATTRIBUTES que descreve os atributos a serem atribuídos ao novo objeto de transmissão de PIO. Antes de chamar esse método, o chamador deve chamar a função WDF_OBJECT_ATTRIBUTES_INIT para inicializar a estrutura. Esse parâmetro é opcional e pode ser especificado como WDF_NO_OBJECT_ATTRIBUTES se o driver do controlador serial não precisar atribuir atributos ao objeto . Para obter mais informações, consulte Comentários.

[out] PioTransmit

Um ponteiro para um local no qual esse método grava um identificador de SERCX2PIOTRANSMIT no objeto pio-transmit recém-criado. O SerCx2 e o driver do controlador serial usam esse identificador em chamadas subsequentes para fazer referência a esse objeto.

Retornar valor

Esse método retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os valores de retorno de erro possíveis incluem os seguintes códigos de status.

Código de retorno	Descrição
STATUS_INVALID_DEVICE_REQUEST	Um objeto pio-transmit já existe de uma chamada SerCx2PioTransmitCreate anterior.
STATUS_INFO_LENGTH_MISMATCH	O valorTamanhoda-> Configuração não é igual a sizeof(SERCX2_PIO_TRANSMIT_CONFIG).
STATUS_INVALID_PARAMETER	A combinação especificada de funções de retorno de chamada implementadas não é válida. O driver deve implementar as funções EvtSerCx2PioTransmitWriteBuffer, EvtSerCx2PioTransmitEnableReadyNotification e EvtSerCx2PioTransmitCancelReadyNotification . O driver deve implementar todas as três ou nenhuma das funções EvtSerCx2PioTransmitDrainFifo, EvtSerCx2PioTransmitCancelDrainFifo e EvtSerCx2PioTransmitPurgeFifo .
STATUS_INSUFFICIENT_RESOURCES	Recursos insuficientes estão disponíveis para executar a operação solicitada.

Comentários

O driver do controlador serial chama esse método para criar um objeto de transmissão de PIO. O SerCx2 usa esse objeto para executar transações de transmissão de PIO, que são transações que usam E/S programada (PIO) para gravar dados no controlador serial a serem transmitidos.

Normalmente, um driver de controlador serial chama SerCx2PioTransmitCreate de sua função EvtDriverDeviceAdd . O driver deve chamar esse método somente depois de chamar com êxito o método SerCx2InitializeDevice .

Como opção, um driver de controlador serial pode usar o parâmetro Attributes para criar um contexto para o objeto PIO-transmit e fornecer ponteiros para as funções EvtCleanupCallback e EvtDestroyCallback que são chamadas para preparar o objeto para exclusão. Para obter mais informações, consulte WDF_OBJECT_ATTRIBUTES.

Se o parâmetro Attributes apontar para uma estrutura WDF_OBJECT_ATTRIBUTES , o chamador não deverá substituir os valores que a função de inicialização WDF_OBJECT_ATTRIBUTES_INIT grava nos membros ParentObject, ExecutionLevel e SynchronizationScope dessa estrutura.

Para obter mais informações sobre como criar objetos de transmissão de PIO, consulte SERCX2PIOTRANSMIT. Para obter mais informações sobre operações de transmissão de PIO, consulte SerCx2 PIO-Transmit Transactions.