SerCx2CustomTransmitCreate-Funktion (sercx.h)

Die SerCx2CustomTransmitCreate-Methode erstellt ein benutzerdefiniertes Übertragungsobjekt, das Version 2 der seriellen Frameworkerweiterung (SerCx2) verwendet, um Daten mithilfe eines benutzerdefinierten Datenübertragungsmechanismus an den seriellen Controller zu schreiben.

Syntax

NTSTATUS SerCx2CustomTransmitCreate(
  [in]  WDFDEVICE                      Device,
  [in]  PSERCX2_CUSTOM_TRANSMIT_CONFIG CustomTransmitConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES         Attributes,
  [out] SERCX2CUSTOMTRANSMIT           *CustomTransmit
);

Parameter

[in] Device

Ein WDFDEVICE-Handle zum 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] CustomTransmitConfig

Ein Zeiger auf eine SERCX2_CUSTOM_TRANSMIT_CONFIG Struktur. Bevor Sie diese Methode aufrufen, muss der Aufrufer die SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT Funktion aufrufen, um die Struktur zu initialisieren. Diese Struktur enthält Zeiger auf eine Reihe von Ereignisanrufroutinen, die vom seriellen Controllertreiber implementiert werden. SerCx2 ruft diese Funktionen auf, um benutzerdefinierte Übertragungen durchzuführen.

[in] Attributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES Struktur, die die Attribute beschreibt, die dem neuen benutzerdefinierten Übertragungsobjekt zugewiesen werden sollen. Bevor Sie diese Methode aufrufen, 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 keine Attribute dem Objekt zuweisen muss. Weitere Informationen finden Sie in den Hinweisen.

[out] CustomTransmit

Ein Zeiger auf einen Speicherort, an dem diese Methode ein SERCX2CUSTOMTRANSMIT-Handle in das neu erstellte benutzerdefinierte Übertragungsobjekt schreibt. SerCx2 und der serielle Controllertreiber verwenden diesen 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 umfassen die folgenden Statuscodes.

Rückgabecode Beschreibung
STATUS_INVALID_DEVICE_REQUEST
Ein benutzerdefiniertes Übertragungsobjekt ist bereits aus einem vorherigen SerCx2CustomTransmitCreate-Aufruf vorhanden; oder ein System-DMA-transmission-Objekt ist aus einem vorherigen SerCx2SystemDmaTransmitCreate-Aufruf vorhanden; oder ein System-DMA-transmission-Objekt ist aus einem vorherigen SerCx2SystemDmaTransmitCreate-Aufruf vorhanden; oder SerCx2PioTransmitCreate wurde noch nicht aufgerufen, um ein PIO-Übertragungsobjekt zu erstellen.
STATUS_INVALID_PARAMETER
Ein Parameterwert ist ungültig.
STATUS_INFO_LENGTH_MISMATCH
Der Wert "Config->Size " entspricht nicht der Größe(SERCX2_CUSTOM_TRANSMIT_CONFIG).
STATUS_INSUFFICIENT_RESOURCES
Unzureichende Ressourcen stehen zum Erstellen des benutzerdefinierten Übertragungsobjekts zur Verfügung.

Bemerkungen

Diese Methode wird vom seriellen Controllertreiber aufgerufen, um ein benutzerdefiniertes Übertragungsobjekt zu erstellen. SerCx2 verwendet dieses Objekt, um benutzerdefinierte Übertragungsvorgänge auszuführen, die Transaktionen sind, die einen benutzerdefinierten Datenübertragungsmechanismus verwenden, um Daten an den seriellen Controller zu schreiben.

Ein serieller Controllertreiber muss die Methoden SerCx2InitializeDevice und SerCx2PioTransmitCreate erfolgreich aufrufen, bevor SerCx2CustomTransmitCreate aufgerufen wird.

Bevor Sie SerCx2CustomTransmitCreate aufrufen, muss der serielle Controllertreiber die SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT-Funktion aufrufen, um die SERCX2_CUSTOM_TRANSMIT_CONFIG Struktur zu initialisieren, die von CustomTransmitConfig darauf verweist. Diese Funktion legt die folgenden Elemente der Struktur auf Null fest:

  • Ausrichtung
  • MinimumTransactionLength
  • MaximumTransactionLength
  • MinimumTransferUnit
  • Exklusiv
Falls erforderlich, kann der serielle Controllertreiber eine dieser Elemente auf nichtzero-Werte festlegen, nachdem die Initialisierungsfunktion zurückgegeben wird. Für die Bequemlichkeit verwendet SerCx2CustomTransmitCreate jedoch die folgenden Standardwerte, wenn diese Elemente null sind:
  • Wenn die Ausrichtung null ist, legt SerCx2 den Datenausrichtungswert auf einen fest, was bedeutet, dass der Schreibpuffer auf einer beliebigen Bytegrenze im Arbeitsspeicher beginnen kann.
  • Wenn MinimumTransactionLength null ist, legt SerCx2 die mindeste Transaktionslä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 Mindestübertragungseinheit auf ein Byte fest.
  • Wenn Exklusiv null (FALSE) ist, ist der exklusive Modus deaktiviert.
Wenn der Aufruftreiber exklusiv auf TRUE festgelegt wird, muss die Elemente MinimumTransferUnit, Ausrichtung und MinimumTransactionLength null sein. Weitere Informationen finden Sie unter SERCX2_CUSTOM_TRANSMIT_CONFIG.

Als Option kann ein serieller Controllertreiber den Parameter Attribute 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 zum Löschen vorzubereiten. Weitere Informationen finden Sie unter WDF_OBJECT_ATTRIBUTES.

Wenn der Parameter "Attribute " auf eine WDF_OBJECT_ATTRIBUTES Struktur verweist, darf der Aufrufer die Werte nicht überschreiben, die die WDF_OBJECT_ATTRIBUTES_INIT Initialisierungsfunktion in die Elemente "ParentObject", " ExecutionLevel" und " SyncScope " dieser Struktur schreibt.

Weitere Informationen zum Erstellen von benutzerdefinierten Übertragungsobjekten finden Sie unter SERCX2CUSTOMTRANSMIT. Weitere Informationen zu benutzerdefinierten Übertragungen finden Sie unter SerCx2 Custom-Transmit Transaktionen.

Requirements (Anforderungen)

   
Unterstützte Mindestversion (Client) Ab Windows 8.1 verfügbar.
Zielplattform Universell
Header sercx.h
IRQL PASSIVE_LEVEL

Weitere Informationen

EvtCleanupCallback

EvtDestroyCallback

EvtDriverDeviceAdd

SERCX2CUSTOMTRANSMIT

SERCX2_CUSTOM_TRANSMIT_CONFIG

SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT

SerCx2InitializeDevice

SerCx2PioTransmitCreate

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT