Funzione SerCx2CustomReceiveTransactionCreate (sercx.h)

Articolo
10/30/2024

Il metodo SerCx2CustomReceiveTransactionCreate crea un oggetto custom-receive-transaction, che la versione 2 dell'estensione del framework seriale (SerCx2) usa per eseguire transazioni di ricezione personalizzate.

Sintassi

NTSTATUS SerCx2CustomReceiveTransactionCreate(
  [in]  SERCX2CUSTOMRECEIVE                       CustomReceive,
  [in]  PSERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG CustomReceiveTransactionConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES                    Attributes,
  [out] SERCX2CUSTOMRECEIVETRANSACTION            *CustomReceiveTransaction
);

Parametri

[in] CustomReceive

Handle di SERCX2CUSTOMRECEIVE a un oggetto di ricezione personalizzato. Il driver del controller seriale precedentemente denominato metodo SerCx2CustomReceiveCreate per creare questo oggetto.

[in] CustomReceiveTransactionConfig

Puntatore a una struttura SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG. Prima di chiamare questo metodo, il chiamante deve chiamare la funzione SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG_INIT per inizializzare la struttura. Questa struttura contiene puntatori a un set di routine di callback degli eventi implementate dal driver del controller seriale. SerCx2 chiama queste funzioni per eseguire una transazione di I/O che usa il meccanismo di trasferimento dei dati personalizzato per leggere i dati ricevuti dal controller seriale.

[in] Attributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che descrive gli attributi da assegnare al nuovo oggetto custom-receive-transaction. Prima di chiamare questo metodo, il chiamante deve chiamare la funzione WDF_OBJECT_ATTRIBUTES_INIT per inizializzare la struttura. Questo parametro è facoltativo e può essere specificato come WDF_NO_OBJECT_ATTRIBUTES se il driver del controller seriale non deve assegnare attributi all'oggetto. Per altre informazioni, vedere Osservazioni.

[out] CustomReceiveTransaction

Puntatore a una posizione in cui questo metodo scrive un handle SERCX2CUSTOMRECEIVETRANSACTION nell'oggetto custom-receive-transaction appena creato. SerCx2 e il driver del controller seriale usano questo handle nelle chiamate successive per fare riferimento a questo oggetto.

Valore restituito

Questo metodo restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti di errore possibili includono i codici di stato seguenti.

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_REQUEST	Un oggetto custom-receive-transaction esiste già da una precedente SerCx2CustomReceiveTransactionCreate chiamata.
STATUS_INFO_LENGTH_MISMATCH	Il valore CustomReceiveTransactionConfigsize non è uguale sizeof(SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG).
STATUS_INVALID_PARAMETER	Un valore di parametro non è valido. Il chiamante deve fornire EvtSerCx2CustomReceiveTransactionStart e EvtSerCx2CustomReceiveTransactionQueryProgress puntatori a funzione.
STATUS_INSUFFICIENT_RESOURCES	Sono disponibili risorse insufficienti per creare l'oggetto custom-receive-transaction.

Osservazioni

Il driver del controller seriale può chiamare questo metodo per creare un oggetto custom-receive-transaction. SerCx2 usa questo oggetto per gestire transazioni di ricezione personalizzate, ovvero transazioni di I/O che usano un meccanismo di trasferimento dati personalizzato per leggere i dati ricevuti dal controller seriale.

Come opzione, un driver del controller seriale può usare il parametro attributi per creare un contesto per l'oggetto di ricezione personalizzato e fornire puntatori a EvtCleanupCallback e Funzioni EvtDestroyCallback chiamate per preparare l'oggetto per l'eliminazione. Per altre informazioni, vedere WDF_OBJECT_ATTRIBUTES.

Se il parametro Attributes punta a una struttura di WDF_OBJECT_ATTRIBUTES, il chiamante non deve sovrascrivere i valori scritti dalla funzione di inizializzazione WDF_OBJECT_ATTRIBUTES_INIT nei ParentObject, ExecutionLevele membri synchronizationScope di questa struttura.

Se la combinazione specificata di funzioni di callback implementate non è valida, la SerCx2CustomReceiveTransactionCreate chiamata ha esito negativo e restituisce STATUS_INVALID_PARAMETER.

Per altre informazioni sulla creazione di oggetti custom-receive-transaction, vedere SERCX2CUSTOMRECEIVETRANSACTION. Per altre informazioni sulle transazioni di ricezione personalizzate, vedere SerCx2 Custom-Receive Transactions.