WDF_IO_TARGET_OPEN_PARAMS-Struktur (wdfiotarget.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WDF_IO_TARGET_OPEN_PARAMS-Struktur enthält Parameter, die von der WdfIoTargetOpen-Methode verwendet werden.

Syntax

typedef struct _WDF_IO_TARGET_OPEN_PARAMS {
  ULONG                             Size;
  WDF_IO_TARGET_OPEN_TYPE           Type;
  PFN_WDF_IO_TARGET_QUERY_REMOVE    EvtIoTargetQueryRemove;
  PFN_WDF_IO_TARGET_REMOVE_CANCELED EvtIoTargetRemoveCanceled;
  PFN_WDF_IO_TARGET_REMOVE_COMPLETE EvtIoTargetRemoveComplete;
  PDEVICE_OBJECT                    TargetDeviceObject;
  PFILE_OBJECT                      TargetFileObject;
  UNICODE_STRING                    TargetDeviceName;
  ACCESS_MASK                       DesiredAccess;
  ULONG                             ShareAccess;
  ULONG                             FileAttributes;
  ULONG                             CreateDisposition;
  ULONG                             CreateOptions;
  PVOID                             EaBuffer;
  ULONG                             EaBufferLength;
  PLONGLONG                         AllocationSize;
  ULONG                             FileInformation;
  UNICODE_STRING                    FileName;
} WDF_IO_TARGET_OPEN_PARAMS, *PWDF_IO_TARGET_OPEN_PARAMS;

Member

Size

Die Größe (in Bytes) dieser Struktur.

Type

Ein WDF_IO_TARGET_OPEN_TYPE typisierter Wert, der den Typ des geöffneten Vorgangs angibt, der von WdfIoTargetOpen ausgeführt wird.

EvtIoTargetQueryRemove

Ein Zeiger auf die EvtIoTargetQueryRemove-Ereignisrückruffunktion des Treibers oder NULL.

EvtIoTargetRemoveCanceled

Ein Zeiger auf die EvtIoTargetRemoveCanceled-Ereignisrückruffunktion des Treibers oder NULL.

EvtIoTargetRemoveComplete

Ein Zeiger auf die EvtIoTargetRemoveComplete-Ereignisrückruffunktion des Treibers oder NULL.

TargetDeviceObject

Dieser Member gilt nicht für UMDF-Treiber.

KMDF Wenn der Wert von TypeWdfIoTargetOpenUseExistingDevice ist, ist dies ein Zeiger auf eine DEVICE_OBJECT Struktur, die das Gerät des E/A-Ziels darstellt. Wenn der Wert von Type nicht WdfIoTargetOpenUseExistingDevice ist, wird dieser Member ignoriert.

TargetFileObject

Dieser Member gilt nicht für UMDF-Treiber.

KMDF Wenn der Wert von TypeWdfIoTargetOpenUseExistingDevice ist, ist dies ein Zeiger auf eine FILE_OBJECT-Struktur . Diese Struktur ist in allen E/A-Anforderungen enthalten, die der Treiber an das E/A-Ziel sendet (siehe WdfRequestGetFileObject). Dieser Member ist optional und kann NULL sein. Wenn der Wert von Type nicht WdfIoTargetOpenUseExistingDevice ist, wird dieser Member ignoriert.

TargetDeviceName

Wenn der Wert von TypeWdfIoTargetOpenByName ist, handelt es sich um eine UNICODE_STRING Struktur, die den Namen eines Geräts, einer Datei oder einer Geräteschnittstelle enthält. Informationen zum Format dieses Namens finden Sie unter Objektnamen.

Wenn der Wert von Type nicht WdfIoTargetOpenByName ist, wird dieser Member ignoriert.

DesiredAccess

Wenn der Wert von TypeWdfIoTargetOpenByName ist, ist dies ein ACCESS_MASK Wert.

Wenn der Wert von Type nicht WdfIoTargetOpenByName ist, wird dieser Member ignoriert.

KMDF Mögliche Werte sind FILE_Xxxx_ACCESS Werte wie FILE_ANY_ACCESS, FILE_SPECIAL_ACCESS, FILE_READ_ACCESS oder FILE_WRITE_ACCESS sowie GENERIC_READ, GENERIC_WRITE und GENERIC_ALL.

UMDF Die am häufigsten verwendeten Werte sind GENERIC_READ, GENERIC_WRITE oder beide (GENERIC_READ | GENERIC_WRITE). Beachten Sie, dass ACCESS_MASK ein DWORD-Wert ist. Weitere Informationen zu diesem Member finden Sie unter dem dwDesiredAccess-Parameter von CreateFile im Windows SDK.

ShareAccess

Wenn der Wert von Type nicht WdfIoTargetOpenByName ist, wird dieser Member ignoriert.

KMDF Wenn der Wert von TypeWdfIoTargetOpenByName ist, ist dies ein bitweises OR der folgenden Flags (die in Wdm.h definiert sind) oder null.

ShareAccess-Flag	Bedeutung
FILE_SHARE_READ	Der Treiber erfordert keinen exklusiven Lesezugriff auf das Gerät.
FILE_SHARE_WRITE	Der Treiber erfordert keinen exklusiven Schreibzugriff auf das Gerät.
FILE_SHARE_DELETE	Der Treiber erfordert keinen exklusiven Löschzugriff auf das Gerät.

UMDF Weitere Informationen zu diesem Member finden Sie im DwShareMode-Parameter der CreateFile-Funktion im Windows SDK.

Der Wert 0 (null) in ShareAccess gibt an, dass der Treiber exklusiven Zugriff auf das Gerät benötigt.

FileAttributes

KMDF Wenn der Wert von TypeWdfIoTargetOpenByName ist, ist dies ein bitweises OR der FILE_ATTRIBUTE_Xxxx-Flags , die in Wdm.h definiert sind. Die meisten Treiber geben FILE_ATTRIBUTE_NORMAL an. Weitere Informationen zu diesen Flags finden Sie unter ZwCreateFile.

UMDF Weitere Informationen zu diesem Member finden Sie im DwFlagsAndAttributes-Parameter der CreateFile-Funktion im Windows SDK.

Wenn der Wert von Type nicht WdfIoTargetOpenByName ist, wird dieser Member ignoriert.

CreateDisposition

KMDF Wenn der Wert von TypeWdfIoTargetOpenByName ist, gibt dieser Wert eine Aktion an, die das System beim Öffnen einer Datei ausführen soll. Eine Liste der möglichen Werte finden Sie unter ZwCreateFile.

UMDF Weitere Informationen zu diesem Member finden Sie im DwCreationDisposition-Parameter der CreateFile-Funktion im Windows SDK.

Wenn der Wert von Type nicht WdfIoTargetOpenByName ist, wird dieser Member ignoriert.

CreateOptions

Dieser Member gilt nicht für UMDF-Treiber.

KMDF Wenn der Wert von TypeWdfIoTargetOpenByName ist, ist dies ein bitweises OR von Dateioptionsflags. Eine Liste der möglichen Flags finden Sie unter ZwCreateFile. Wenn der Wert von Type nicht WdfIoTargetOpenByName ist, wird dieser Member ignoriert.

EaBuffer

Dieser Member gilt nicht für UMDF-Treiber.

KMDF Wenn der Wert von TypeWdfIoTargetOpenByName ist, verweist dieser Member auf einen erweiterten Attributpuffer. In der Regel geben Treiber NULL für diesen Wert an. Wenn der Wert von Type nicht WdfIoTargetOpenByName ist, wird dieser Member ignoriert.

EaBufferLength

Dieser Member gilt nicht für UMDF-Treiber.

KMDF Wenn der Wert von TypeWdfIoTargetOpenByName ist, ist dies die Länge des Puffers für erweiterte Attribute. In der Regel stellen Treiber 0 (null) für diesen Wert bereit. Wenn der Wert von Type nicht WdfIoTargetOpenByName ist, wird dieser Member ignoriert.

AllocationSize

Dieser Member gilt nicht für UMDF-Treiber.

KMDF Wenn der Wert von TypeWdfIoTargetOpenByName ist, gibt dieser Member die Größe in Bytes an, die das System zunächst für die Datei zuordnen soll, wenn es eine neue Datei erstellt. Dieser Wert ist optional und kann null sein. Wenn der Wert von Type nicht WdfIoTargetOpenByName ist, wird dieser Member ignoriert.

FileInformation

Dieser Member gilt nicht für UMDF-Treiber.

KMDF Wenn der Wert von TypeWdfIoTargetOpenByName ist, empfängt dieser Member status Informationen, wenn der Aufruf von WdfIoTargetOpen zurückgibt. Die Informationen sind einer der folgenden Werte: FILE_CREATED, FILE_OPENED, FILE_OVERWRITTEN, FILE_SUPERSEDED, FILE_EXISTS oder FILE_DOES_NOT_EXIST. Wenn der Wert von Type nicht WdfIoTargetOpenByName ist, wird dieser Member ignoriert.

FileName

Dieser Member gilt nicht für KMDF-Treiber.

UMDF Eine UNICODE_STRING-Struktur, die den Namen der Datei enthält, aus der ein Dateiobjekt erstellt werden soll. Dieser Member ist optional und gilt nur, wenn der Wert von TypeWdfIoTargetOpenLocalTargetByFile ist. Die meisten Treiber geben hier NULL an, es sei denn, das untere Ziel unterstützt den Gerätenamespacezugriff. Wenn angegeben, darf die Zeichenfolge keine Pfadtrennzeichen (Schrägstrich oder umgekehrter Schrägstrich) enthalten.

Hinweise

Treiber sollten die WDF_IO_TARGET_OPEN_PARAMS-Struktur initialisieren, indem sie eine der folgenden Funktionen aufrufen:

WDF_IO_TARGET_OPEN_PARAMS_INIT_EXISTING_DEVICE, wenn Ihr Treiber ein Zielgerät identifizieren kann, indem er einen Zeiger auf eine DEVICE_OBJECT-Struktur eingibt.
WDF_IO_TARGET_OPEN_PARAMS_INIT_CREATE_BY_NAME, wenn das E/A-Ziel ein Gerät, eine Datei oder eine Geräteschnittstelle ist und ob Ihr Treiber den Namen des Geräts, der Datei oder der Geräteschnittstelle angeben kann. Wenn Sie den Namen einer bereits vorhandenen Datei angeben, ersetzt das System die vorhandene Datei. Wenn die Datei nicht vorhanden ist, wird sie vom System erstellt.
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME, wenn das E/A-Ziel ein Gerät, eine Datei oder eine Geräteschnittstelle ist und ob Ihr Treiber den Namen des Geräts, der Datei oder der Geräteschnittstelle angeben kann. Wenn Sie den Namen einer bereits vorhandenen Datei angeben, öffnet das System die vorhandene Datei. Wenn die Datei nicht vorhanden ist, tritt beim Öffnen ein Fehler auf.
WDF_IO_TARGET_OPEN_PARAMS_INIT_REOPEN, wenn die EvtIoTargetRemoveCanceled-Rückruffunktion Ihres Treibers ein E/A-Remoteziel erneut öffnet, weil das Gerät nicht entfernt wurde.
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, wenn Ihr UMDF-Treiber vom Treiber erstellte Anforderungen an niedrigere Ziele senden muss, die ein zugeordnetes Dateiobjekt erfordern.