Função SerCx2CustomTransmitTransactionCreate (sercx.h)

Artigo
10/30/2024

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

Sintaxe

NTSTATUS SerCx2CustomTransmitTransactionCreate(
  [in]  SERCX2CUSTOMTRANSMIT                       CustomTransmit,
  [in]  PSERCX2_CUSTOM_TRANSMIT_TRANSACTION_CONFIG CustomTransmitTransactionConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES                     Attributes,
  [out] SERCX2CUSTOMTRANSMITTRANSACTION            *CustomTransmitTransaction
);

Parâmetros

[in] CustomTransmit

Um identificador de SERCX2CUSTOMTRANSMIT para um objeto de transmissão personalizada. O driver do controlador serial anteriormente chamou o método SerCx2CustomTransmitCreate para criar esse objeto.

[in] CustomTransmitTransactionConfig

Um ponteiro para uma estrutura de SERCX2_CUSTOM_TRANSMIT_TRANSACTION_CONFIG. Antes de chamar esse método, o chamador deve chamar a função SERCX2_CUSTOM_TRANSMIT_TRANSACTION_CONFIG_INIT para inicializar a estrutura. Essa estrutura contém ponteiros para um conjunto de rotinas de retorno de chamada de evento que são implementadas pelo driver do controlador serial. O SerCx2 chama essas funções para fazer uma transação de E/S que usa o mecanismo de transferência de dados personalizado para gravar dados no controlador serial a serem transmitidos.

[in] Attributes

Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES que descreve os atributos a serem atribuídos ao novo objeto de transação de transmissão personalizada. 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] CustomTransmitTransaction

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

Valor de retorno

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 custom-transmit-transaction já existe de uma chamada SerCx2CustomTransmitTransactionCreate anterior.
STATUS_INFO_LENGTH_MISMATCH	O valor CustomTransmitTransactionConfig não é igual ao tamanho de(SERCX2_CUSTOM_TRANSMIT_TRANSACTION_CONFIG).
STATUS_INVALID_PARAMETER	Um valor de parâmetro não é válido. O chamador deve fornecer um ponteiro de função EvtSerCx2CustomTransmitTransactionStart válido.
STATUS_INSUFFICIENT_RESOURCES	Recursos insuficientes estão disponíveis para criar o objeto custom-transmit-transaction.

Observações

O driver do controlador serial pode chamar esse método para criar um objeto de transação de transmissão personalizada. O SerCx2 usa esse objeto para gerenciar transações de transmissão personalizada, que são transações de E/S que usam um mecanismo de transferência de dados personalizado para gravar dados no controlador serial a serem transmitidos.

Como opção, um driver de controlador serial pode usar o parâmetro Attributes para criar um contexto para o objeto de transmissão personalizada e fornecer ponteiros para EvtCleanupCallback e EvtDestroyCallback funções 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 no ParentObject, ExecutionLevele SynchronizationScope membros dessa estrutura.

Se a combinação especificada de funções de retorno de chamada implementadas não for válida, SerCx2CustomTransmitTransactionCreate falhará e retornará STATUS_INVALID_PARAMETER.

Para obter mais informações sobre como criar objetos de transação de transmissão personalizada, consulte SERCX2CUSTOMTRANSMITTRANSACTION. Para obter mais informações sobre transações de transmissão personalizada, consulte transações de Custom-Transmit SerCx2.