SerCx2CustomReceiveCreate-Funktion (sercx.h)

Artikel
10/30/2024

Die SerCx2CustomReceiveCreate-Methode erstellt ein objekt für den benutzerdefinierten Empfang, das version 2 der seriellen Frameworkerweiterung (SerCx2) zum Lesen von Daten vom seriellen Controller mithilfe eines benutzerdefinierten Datenübertragungsmechanismus verwendet.

Syntax

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

Parameter

[in] Device

Ein WDFDEVICE-Handle für das Framework-Geräteobjekt, das den seriellen Controller darstellt. Der serielle Controllertreiber hat dieses Objekt in seiner EvtDriverDeviceAdd Rückruffunktion erstellt. Weitere Informationen finden Sie unter SerCx2InitializeDevice.

[in] CustomReceiveConfig

Ein Zeiger auf eine SERCX2_CUSTOM_RECEIVE_CONFIG Struktur. Vor dem Aufrufen dieser Methode muss der Aufrufer die SERCX2_CUSTOM_RECEIVE_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 transaktionen mit benutzerdefiniertem Empfang auszuführen.

[in] Attributes

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

Ein Zeiger auf eine Position, an die diese Methode ein SERCX2CUSTOMRECEIVE Handle in das neu erstellte benutzerdefinierte Empfangsobjekt 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 den benutzerdefinierten Empfang ist bereits aus einem vorherigen SerCx2CustomReceiveCreate Aufruf vorhanden; oder ein System-DMA-Receive-Objekt ist aus einem vorherigen SerCx2CustomReceiveCreate Aufruf vorhanden; oder ein System-DMA-Transmit-Objekt ist aus einem vorherigen SerCx2CustomTransmitCreate Aufruf vorhanden; oder SerCx2PioReceiveCreate wurde noch nicht aufgerufen, um ein PIO-Empfangsobjekt zu erstellen.
STATUS_INVALID_PARAMETER	Ein Parameterwert ist ungültig.
STATUS_INFO_LENGTH_MISMATCH	Der Wert Config->Size entspricht nicht Sizeof(SERCX2_CUSTOM_RECEIVE_CONFIG).
STATUS_INSUFFICIENT_RESOURCES	Unzureichende Ressourcen stehen zum Erstellen des benutzerdefinierten Empfangsobjekts zur Verfügung.

Bemerkungen

Diese Methode wird vom seriellen Controllertreiber aufgerufen, um ein benutzerdefiniertes Empfangsobjekt zu erstellen. SerCx2 verwendet dieses Objekt zum Ausführen von benutzerdefinierten Empfangen-Transaktionen, bei denen es sich um Transaktionen handelt, die einen benutzerdefinierten Datenübertragungsmechanismus verwenden, um vom seriellen Controller empfangene Daten zu lesen.

Ein serieller Controllertreiber muss die methoden SerCx2InitializeDevice und SerCx2PioReceiveCreate Methoden aufrufen, bevor SerCx2CustomReceiveCreateaufgerufen wird.

Vor dem Aufruf SerCx2CustomReceiveCreatemuss der serielle Controllertreiber die SERCX2_CUSTOM_RECEIVE_CONFIG_INIT-Funktion aufrufen, um die SERCX2_CUSTOM_RECEIVE_CONFIG Struktur zu initialisieren, auf die CustomReceiveConfig-verweist. Diese Funktion legt die folgenden Elemente der Struktur auf Null fest:

Ausrichtung
MinimumTransactionLength-
MaximumTransactionLength-
MinimumTransferUnit
Exklusive

Bei Bedarf kann der serielle Controllertreiber eines dieser Member auf Nichtzerowerte festlegen, nachdem die Initialisierungsfunktion zurückgegeben wurde. Aus Gründen der Einfachheit verwendet SerCx2CustomReceiveCreate die folgenden Standardwerte, wenn diese Member null sind:

Wenn Ausrichtung null ist, legt SerCx2 den Datenausrichtungswert auf einen fest, was bedeutet, dass der Lesepuffer auf einer beliebigen Bytegrenze im Arbeitsspeicher beginnen kann.
Wenn MinimumTransactionLength null ist, legt SerCx2 die Mindesttransaktionslänge auf ein Byte fest.
Wenn MaximumTransactionLength null ist, legt SerCx2 die maximale Transaktionslänge auf ((ULONG)-1) fest.
Wenn MinimumTransferUnit- null ist, legt SerCx2 die minimale Übertragungseinheit auf ein Byte fest.
Wenn Exklusiv- null (FALSE) ist, ist der exklusive Modus deaktiviert.

Wenn der aufrufende Treiber Exclusive auf TRUEfestlegt, muss die MinimumTransferUnit, Alignmentund MinimumTransactionLength Member null sein. Weitere Informationen finden Sie unter SERCX2_CUSTOM_RECEIVE_CONFIG.

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.

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