SerCx2CustomReceiveTransactionCreate-Funktion (sercx.h)

Artikel
10/30/2024

Die SerCx2CustomReceiveTransactionCreate-Methode erstellt ein objekt für benutzerdefinierte Empfangstransaktion, das Version 2 der seriellen Framework-Erweiterung (SerCx2) zum Ausführen von benutzerdefinierten Empfangen-Transaktionen verwendet.

Syntax

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

Parameter

[in] CustomReceive

Ein SERCX2CUSTOMRECEIVE Handle für ein benutzerdefiniertes Empfangsobjekt. Der serielle Controllertreiber hat zuvor den SerCx2CustomReceiveCreate Methode aufgerufen, um dieses Objekt zu erstellen.

[in] CustomReceiveTransactionConfig

Ein Zeiger auf eine SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG Struktur. Vor dem Aufrufen dieser Methode muss der Aufrufer die SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG_INIT-Funktion aufrufen, um die Struktur zu initialisieren. Diese Struktur enthält Zeiger auf eine Reihe von Ereignisrückrufroutinen, die vom seriellen Controllertreiber implementiert werden. SerCx2 ruft diese Funktionen auf, um eine E/A-Transaktion durchzuführen, die den benutzerdefinierten Datenübertragungsmechanismus verwendet, um vom seriellen Controller empfangene Daten zu lesen.

[in] Attributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES-Struktur, die die Attribute beschreibt, die dem neuen benutzerdefinierten Empfangstransaktionsobjekt zugewiesen werden sollen. Vor dem Aufrufen dieser Methode muss der Aufrufer die WDF_OBJECT_ATTRIBUTES_INIT-Funktion aufrufen, um die Struktur zu initialisieren. Dieser Parameter ist optional und kann als WDF_NO_OBJECT_ATTRIBUTES angegeben werden, wenn der serielle Controllertreiber dem Objekt keine Attribute zuweisen muss. Weitere Informationen finden Sie in den Hinweisen.

[out] CustomReceiveTransaction

Ein Zeiger auf eine Position, an die diese Methode ein SERCX2CUSTOMRECEIVETRANSACTION Handle in das neu erstellte objekt für benutzerdefinierte Empfangen-Transaktion schreibt. SerCx2 und der serielle Controllertreiber verwenden dieses Handle in nachfolgenden Aufrufen, um auf dieses Objekt zu verweisen.

Rückgabewert

Diese Methode gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Mögliche Fehlerrückgabewerte sind die folgenden Statuscodes.

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_REQUEST	Ein objekt für die benutzerdefinierte Empfangstransaktion ist bereits aus einem vorherigen SerCx2CustomReceiveTransactionCreate Aufruf vorhanden.
STATUS_INFO_LENGTH_MISMATCH	Der Wert CustomReceiveTransactionConfig->Size entspricht nicht Sizeof(SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG).
STATUS_INVALID_PARAMETER	Ein Parameterwert ist ungültig. Der Aufrufer muss gültige EvtSerCx2CustomReceiveTransactionStart und EvtSerCx2CustomReceiveTransactionQueryProgress Funktionszeiger bereitstellen.
STATUS_INSUFFICIENT_RESOURCES	Unzureichende Ressourcen sind verfügbar, um das objekt für die benutzerdefinierte Empfangen-Transaktion zu erstellen.

Bemerkungen

Ihr serieller Controllertreiber kann diese Methode aufrufen, um ein benutzerdefiniertes Empfangstransaktionsobjekt zu erstellen. SerCx2 verwendet dieses Objekt zum Verwalten von transaktionen mit benutzerdefiniertem Empfang, bei denen es sich um E/A-Transaktionen handelt, die einen benutzerdefinierten Datenübertragungsmechanismus verwenden, um vom seriellen Controller empfangene Daten zu lesen.

Als Option kann ein serieller Controllertreiber den parameter Attributes verwenden, um einen Kontext für das objekt für den benutzerdefinierten Empfang zu erstellen und Zeiger auf EvtCleanupCallback und EvtDestroyCallback Funktionen zu liefern, die aufgerufen werden, um das Objekt zum Löschen vorzubereiten. Weitere Informationen finden Sie unter WDF_OBJECT_ATTRIBUTES.

Wenn der parameter Attributes auf eine WDF_OBJECT_ATTRIBUTES-Struktur verweist, darf der Aufrufer die Werte, die die WDF_OBJECT_ATTRIBUTES_INIT Initialisierungsfunktion schreibt, nicht in die ParentObject-, ExecutionLevelund SynchronizationScope Member dieser Struktur überschreiben.

Wenn die angegebene Kombination von implementierten Rückruffunktionen ungültig ist, schlägt der SerCx2CustomReceiveTransactionCreate Aufruf fehl und gibt STATUS_INVALID_PARAMETER zurück.

Weitere Informationen zum Erstellen von benutzerdefinierten Empfangstransaktionsobjekten finden Sie unter SERCX2CUSTOMRECEIVETRANSACTION. Weitere Informationen zu transaktionen mit benutzerdefiniertem Empfang finden Sie unter SerCx2 Custom-Receive Transactions.