Funzione SerCx2CustomReceiveCreate (sercx.h)

Articolo
10/30/2024

Il metodo SerCx2CustomReceiveCreate crea un oggetto receive personalizzato, che la versione 2 dell'estensione del framework seriale (SerCx2) usa per leggere i dati dal controller seriale tramite un meccanismo di trasferimento dati personalizzato.

Sintassi

NTSTATUS SerCx2CustomReceiveCreate(
  [in]  WDFDEVICE                     Device,
  [in]  PSERCX2_CUSTOM_RECEIVE_CONFIG CustomReceiveConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out] SERCX2CUSTOMRECEIVE           *CustomReceive
);

Parametri

[in] Device

Handle WDFDEVICE per l'oggetto dispositivo framework che rappresenta il controller seriale. Il driver del controller seriale ha creato questo oggetto nel relativo EvtDriverDeviceAdd funzione di callback. Per altre informazioni, vedere SerCx2InitializeDevice.

[in] CustomReceiveConfig

Puntatore a una struttura SERCX2_CUSTOM_RECEIVE_CONFIG. Prima di chiamare questo metodo, il chiamante deve chiamare la funzione SERCX2_CUSTOM_RECEIVE_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 transazioni di ricezione personalizzate.

[in] Attributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che descrive gli attributi da assegnare al nuovo oggetto di ricezione personalizzato. 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] CustomReceive

Puntatore a una posizione in cui questo metodo scrive un handle SERCX2CUSTOMRECEIVE nell'oggetto di ricezione personalizzato 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	Esiste già un oggetto di ricezione personalizzato da una precedente SerCx2CustomReceiveCreate chiamata; o un oggetto system-DMA-receive esiste da una precedente SerCx2CustomReceiveCreate chiamata; o un oggetto system-DMA-transmit esiste da una precedente SerCx2CustomTransmitCreate chiamata; o SerCx2PioReceiveCreate non è ancora stato chiamato per creare un oggetto di ricezione PIO.
STATUS_INVALID_PARAMETER	Un valore di parametro non è valido.
STATUS_INFO_LENGTH_MISMATCH	Il valoreDimensioni configurazione non è uguale sizeof(SERCX2_CUSTOM_RECEIVE_CONFIG).
STATUS_INSUFFICIENT_RESOURCES	Sono disponibili risorse insufficienti per creare l'oggetto di ricezione personalizzato.

Osservazioni

Questo metodo viene chiamato dal driver del controller seriale per creare un oggetto di ricezione personalizzato. SerCx2 usa questo oggetto per eseguire transazioni di ricezione personalizzate, ovvero transazioni che usano un meccanismo di trasferimento dati personalizzato per leggere i dati ricevuti dal controller seriale.

Un driver del controller seriale deve chiamare correttamente i metodi SerCx2InitializeDevice e SerCx2PioReceiveCreate prima di chiamare SerCx2CustomReceiveCreate.

Prima di chiamare SerCx2CustomReceiveCreate, il driver del controller seriale deve chiamare la funzione SERCX2_CUSTOM_RECEIVE_CONFIG_INIT per inizializzare la struttura SERCX2_CUSTOM_RECEIVE_CONFIG a cui punta CustomReceiveConfig. Questa funzione imposta i membri seguenti della struttura su zero:

allineamento
minimumTransactionLength
MaximumTransactionLength
minimumTransferUnit
esclusivo

Se necessario, il driver del controller seriale può impostare uno di questi membri su valori diversi da zero dopo la restituzione della funzione di inizializzazione. Tuttavia, per praticità, SerCx2CustomReceiveCreate usa i valori predefiniti seguenti se questi membri sono zero:

Se allineamento è zero, SerCx2 imposta il valore di allineamento dei dati su uno, il che significa che il buffer di lettura può iniziare su un limite di byte arbitrario in memoria.
Se minimumTransactionLength è zero, SerCx2 imposta la lunghezza minima della transazione su un byte.
Se MaximumTransactionLength è zero, SerCx2 imposta la lunghezza massima della transazione su ((ULONG)-1).
Se minimumTransferUnit è zero, SerCx2 imposta l'unità di trasferimento minima su un byte.
Se esclusivo è zero (FALSE), la modalità esclusiva è disabilitata.

Se il driver chiamante imposta exclusive su TRUE, i membri MinimumTransferUnit, Alignmente MinimumTransactionLength devono essere zero. Per altre informazioni, vedere SERCX2_CUSTOM_RECEIVE_CONFIG.

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.

Per altre informazioni sulla creazione di oggetti di ricezione personalizzati, vedere SERCX2CUSTOMRECEIVE. Per altre informazioni sulle transazioni di ricezione personalizzate, vedere SerCx2 Custom-Receive Transactions.