SerCx2CustomTransmitTransactionCreate-Funktion (sercx.h)

Artikel
10/30/2024

Mit der SerCx2CustomTransmitTransactionCreate-Methode wird ein objekt für benutzerdefinierte Übertragungen erstellt, das Version 2 der seriellen Framework-Erweiterung (SerCx2) zum Ausführen von benutzerdefinierten Übertragungstransaktionen verwendet.

Syntax

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

Parameter

[in] CustomTransmit

Ein SERCX2CUSTOMTRANSMIT Handle für ein benutzerdefiniertes Übertragungsobjekt. Der serielle Controllertreiber hat zuvor den SerCx2CustomTransmitCreate Methode aufgerufen, um dieses Objekt zu erstellen.

[in] CustomTransmitTransactionConfig

Ein Zeiger auf eine SERCX2_CUSTOM_TRANSMIT_TRANSACTION_CONFIG Struktur. Vor dem Aufrufen dieser Methode muss der Aufrufer die SERCX2_CUSTOM_TRANSMIT_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 Daten in den seriellen Controller zu schreiben, der übertragen werden soll.

[in] Attributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES-Struktur, die die Attribute beschreibt, die dem neuen benutzerdefinierten Übertragungstransaktionsobjekt 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] CustomTransmitTransaction

Ein Zeiger auf eine Position, an die diese Methode ein SERCX2CUSTOMTRANSMITTRANSACTION Handle in das neu erstellte benutzerdefinierte Übertragungstransaktionsobjekt 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 benutzerdefiniertes Übertragungstransaktionsobjekt ist bereits aus einem vorherigen SerCx2CustomTransmitTransactionCreate Aufruf vorhanden.
STATUS_INFO_LENGTH_MISMATCH	Der wert CustomTransmitTransactionConfig->Size entspricht nicht Sizeof(SERCX2_CUSTOM_TRANSMIT_TRANSACTION_CONFIG).
STATUS_INVALID_PARAMETER	Ein Parameterwert ist ungültig. Der Aufrufer muss einen gültigen EvtSerCx2CustomTransmitTransactionStart Funktionszeiger angeben.
STATUS_INSUFFICIENT_RESOURCES	Unzureichende Ressourcen sind verfügbar, um das objekt für die benutzerdefinierte Übertragungstransaktion zu erstellen.

Bemerkungen

Ihr serieller Controllertreiber kann diese Methode aufrufen, um ein benutzerdefiniertes Übertragungstransaktionsobjekt zu erstellen. SerCx2 verwendet dieses Objekt zum Verwalten von transaktionen mit benutzerdefinierten Übertragungen, bei denen es sich um E/A-Transaktionen handelt, die einen benutzerdefinierten Datenübertragungsmechanismus verwenden, um Daten in den seriellen Controller zu schreiben, der übertragen werden soll.

Als Option kann ein serieller Controllertreiber den parameter Attributes verwenden, um einen Kontext für das benutzerdefinierte Übertragungsobjekt zu erstellen und Zeiger auf EvtCleanupCallback und EvtDestroyCallback Funktionen zu liefern, die aufgerufen werden, um das Objekt für den Löschvorgang 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 SerCx2CustomTransmitTransactionCreate fehl und gibt STATUS_INVALID_PARAMETER zurück.

Weitere Informationen zum Erstellen von benutzerdefinierten Übertragungstransaktionsobjekten finden Sie unter SERCX2CUSTOMTRANSMITTRANSACTION. Weitere Informationen zu benutzerdefinierten Übertragungstransaktionen finden Sie unter SerCx2 Custom-Transmit Transactions.