WDF_IO_TARGET_OPEN_PARAMS Struktur (wdfiotarget.h)

Artikel
03/22/2025

[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;

Elemente

Size

Die Größe dieser Struktur in Byte.

Type

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

EvtIoTargetQueryRemove

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

EvtIoTargetRemoveCanceled

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

EvtIoTargetRemoveComplete

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

TargetDeviceObject

Dieses Mitglied gilt nicht für UMDF-Treiber.

KMDF- Wenn der Wert TypeWdfIoTargetOpenUseExistingDeviceist, ist dies ein Zeiger auf eine DEVICE_OBJECT Struktur, die das Gerät des E/A-Ziels darstellt. Wenn der Wert von Type nicht WdfIoTargetOpenUseExistingDeviceist, wird dieses Element ignoriert.

TargetFileObject

Dieses Mitglied gilt nicht für UMDF-Treiber.

KMDF-Wenn der Wert TypeWdfIoTargetOpenUseExistingDeviceist, 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). Dieses Element ist optional und kann NULL-sein. Wenn der Wert von Type nicht WdfIoTargetOpenUseExistingDeviceist, wird dieses Element ignoriert.

TargetDeviceName

Wenn der Wert von TypeWdfIoTargetOpenByNameist, ist dies 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 WdfIoTargetOpenByNameist, wird dieses Element ignoriert.

DesiredAccess

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

Wenn der Wert von Type nicht WdfIoTargetOpenByNameist, wird dieses Element ignoriert.

KMDF-Mögliche Werte umfassen 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 beides (GENERIC_READ | GENERIC_WRITE). Beachten Sie, dass ACCESS_MASK ein DWORD-Wert ist. Weitere Informationen zu diesem Member finden Sie im dwDesiredAccess Parameter von CreateFile im Windows SDK.

ShareAccess

Wenn der Wert von Type nicht WdfIoTargetOpenByNameist, wird dieses Element ignoriert.

KMDF-Wenn der Wert von TypeWdfIoTargetOpenByNameist, ist dies ein bitweiser OR der folgenden Flags (die in Wdm.hdefiniert sind) oder Null.

ShareAccess-Kennzeichnung	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 Funktion CreateFile im Windows SDK.

Ein Wert von Null in ShareAccess gibt an, dass der Treiber exklusiven Zugriff auf das Gerät erfordert.

FileAttributes

KMDF-Wenn der Wert von TypeWdfIoTargetOpenByNameist, ist dies ein bitweiser OR der FILE_ATTRIBUTE_Xxxx Flags, die in Wdm.hdefiniert 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 Funktion CreateFile im Windows SDK.

Wenn der Wert von Type nicht WdfIoTargetOpenByNameist, wird dieses Element ignoriert.

CreateDisposition

KMDF-Wenn der Wert Typ-WdfIoTargetOpenByNameist, 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 Funktion CreateFile im Windows SDK.

Wenn der Wert von Type nicht WdfIoTargetOpenByNameist, wird dieses Element ignoriert.

CreateOptions

Dieses Mitglied gilt nicht für UMDF-Treiber.

KMDF-Wenn der Wert TypeWdfIoTargetOpenByNameist, ist dies ein bitweises ODER von Dateioptionskennzeichnungen. Eine Liste der möglichen Flags finden Sie unter ZwCreateFile. Wenn der Wert von Type nicht WdfIoTargetOpenByNameist, wird dieses Element ignoriert.

EaBuffer

Dieses Mitglied gilt nicht für UMDF-Treiber.

KMDF-Wenn der Wert TypeWdfIoTargetOpenByNameist, verweist dieses Element auf einen erweiterten Attributpuffer. In der Regel geben Treiber NULL- für diesen Wert an. Wenn der Wert von Type nicht WdfIoTargetOpenByNameist, wird dieses Element ignoriert.

EaBufferLength

Dieses Mitglied gilt nicht für UMDF-Treiber.

KMDF-Wenn der Wert TypeWdfIoTargetOpenByNameist, ist dies die Länge des Puffers für erweiterte Attribute. In der Regel geben Treiber null für diesen Wert an. Wenn der Wert von Type nicht WdfIoTargetOpenByNameist, wird dieses Element ignoriert.

AllocationSize

Dieses Mitglied gilt nicht für UMDF-Treiber.

KMDF-Wenn der Wert TypeWdfIoTargetOpenByNameist, gibt dieses Element die Größe in Byte an, die das System zunächst für die Datei zuweisen soll, wenn eine neue Datei erstellt wird. Dieser Wert ist optional und kann null sein. Wenn der Wert von Type nicht WdfIoTargetOpenByNameist, wird dieses Element ignoriert.

FileInformation

Dieses Mitglied gilt nicht für UMDF-Treiber.

KMDF-Wenn der Wert TypeWdfIoTargetOpenByNameist, empfängt dieses Element Statusinformationen, wenn der Aufruf von WdfIoTargetOpen zurückgegeben wird. 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 WdfIoTargetOpenByNameist, wird dieses Element ignoriert.

FileName

Dieses Mitglied 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. Dieses Element ist optional und gilt nur, wenn der Wert von TypeWdfIoTargetOpenLocalTargetByFileist. Die meisten Treiber geben NULL- hier an, es sei denn, das untere Ziel unterstützt Device Namespace Access. Wenn angegeben, darf die Zeichenfolge keine Pfadtrennzeichen (Schrägstrich oder umgekehrter Schrägstrich) enthalten.

Bemerkungen

Treiber sollten die WDF_IO_TARGET_OPEN_PARAMS Struktur initialisieren, indem eine der folgenden Funktionen aufgerufen wird:

WDF_IO_TARGET_OPEN_PARAMS_INIT_EXISTING_DEVICE, wenn Ihr Treiber ein Zielgerät identifizieren kann, indem ein Zeiger auf eine DEVICE_OBJECT Struktur bereitgestellt wird.
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 ihr Treiber den Namen des Geräts, der Datei oder der Geräteschnittstelle angeben kann. Wenn Sie den Namen einer datei angeben, die bereits vorhanden ist, ersetzt das System die vorhandene Datei. Wenn die Datei nicht vorhanden ist, erstellt das System sie.
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 ihr Treiber den Namen des Geräts, der Datei oder der Geräteschnittstelle angeben kann. Wenn Sie den Namen einer datei angeben, die bereits vorhanden ist, öffnet das System die vorhandene Datei. Wenn die Datei nicht vorhanden ist, schlägt der Öffnenvorgang fehl.
WDF_IO_TARGET_OPEN_PARAMS_INIT_REOPEN, wenn die EvtIoTargetRemoveCanceled Rückruffunktion ein Remote-E/A-Ziel erneut öffnet, da das Gerät nicht entfernt wurde.
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, wenn Ihr UMDF-Treiber anforderungen von Treibern an niedrigere Ziele senden muss, für die ein zugeordnetes Dateiobjekt erforderlich ist.