SerCx2PioReceiveCreate-Funktion (sercx.h)

Artikel
10/30/2024

Die SerCx2PioReceiveCreate-Methode erstellt ein PIO-Empfangsobjekt, das Version 2 der seriellen Framework-Erweiterung (SerCx2) zum Ausführen von PIO-Empfangstransaktionen verwendet.

Syntax

NTSTATUS SerCx2PioReceiveCreate(
  [in]           WDFDEVICE                  Device,
  [in]           PSERCX2_PIO_RECEIVE_CONFIG PioReceiveConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES     Attributes,
  [out]          SERCX2PIORECEIVE           *PioReceive
);

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] PioReceiveConfig

Ein Zeiger auf eine SERCX2_PIO_RECEIVE_CONFIG Struktur. Vor dem Aufrufen dieser Methode muss der Aufrufer die SERCX2_PIO_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 PIO-Empfangen-Transaktionen auszuführen.

[in, optional] Attributes

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

Ein Zeiger auf eine Position, an die diese Methode ein SERCX2PIORECEIVE Handle in das neu erstellte PIO-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 PIO-Empfangsobjekt ist bereits aus einem vorherigen SerCx2PioReceiveCreate Aufruf vorhanden.
STATUS_INFO_LENGTH_MISMATCH	Der Wert ConfigSize entspricht nicht Sizeof(SERCX2_PIO_RECEIVE_CONFIG).
STATUS_INVALID_PARAMETER	Die angegebene Kombination implementierter Rückruffunktionen ist ungültig. Der Treiber muss die EvtSerCx2PioReceiveReadBuffer, EvtSerCx2PioReceiveEnableReadyNotificationund EvtSerCx2PioReceiveCancelReadyNotification Funktionen implementieren.
STATUS_INSUFFICIENT_RESOURCES	Unzureichende Ressourcen sind verfügbar, um den angeforderten Vorgang auszuführen.

Bemerkungen

Ihr serieller Controllertreiber ruft diese Methode auf, um ein PIO-Empfangsobjekt zu erstellen. SerCx2 verwendet dieses Objekt zum Ausführen von PIO-Empfangstransaktionen, die programmierte E/A (PIO) verwenden, um vom seriellen Controller empfangene Daten zu lesen.

In der Regel ruft ein serieller Controllertreiber SerCx2PioReceiveCreate aus seiner EvtDriverDeviceAdd--Funktion auf. Der Treiber muss diese Methode erst aufrufen, nachdem die SerCx2InitializeDevice-Methode erfolgreich aufgerufen wurde.

Als Option kann ein serieller Controllertreiber den parameter Attributes verwenden, um einen Kontext für das PIO-Empfangsobjekt 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.

Weitere Informationen zum Erstellen von PIO-Empfangsobjekten finden Sie unter SERCX2PIORECEIVE. Weitere Informationen zu PIO-Empfangstransaktionen finden Sie unter SerCx2 PIO-Receive Transactions.