struktur WDF_IO_TARGET_OPEN_PARAMS (wdfiotarget.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Struktur WDF_IO_TARGET_OPEN_PARAMS berisi parameter yang digunakan metode WdfIoTargetOpen .

Sintaks

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;

Anggota

Size

Ukuran, dalam byte, dari struktur ini.

Type

Nilai yang WDF_IO_TARGET_OPEN_TYPE ketik, yang menunjukkan jenis operasi terbuka yang akan dilakukan WdfIoTargetOpen .

EvtIoTargetQueryRemove

Penunjuk ke fungsi panggilan balik peristiwa EvtIoTargetQueryRemove driver, atau NULL.

EvtIoTargetRemoveCanceled

Penunjuk ke fungsi panggilan balik peristiwa EvtIoTargetRemoveCanceled driver, atau NULL.

EvtIoTargetRemoveComplete

Penunjuk ke fungsi panggilan balik peristiwa EvtIoTargetRemoveComplete driver, atau NULL.

TargetDeviceObject

Anggota ini tidak berlaku untuk driver UMDF.

KMDF Jika nilai Jenis adalah WdfIoTargetOpenUseExistingDevice, ini adalah penunjuk ke struktur DEVICE_OBJECT yang mewakili perangkat target I/O. Jika nilai Jenis bukan WdfIoTargetOpenUseExistingDevice, anggota ini diabaikan.

TargetFileObject

Anggota ini tidak berlaku untuk driver UMDF.

KMDF Jika nilai Jenis adalah WdfIoTargetOpenUseExistingDevice, ini adalah penunjuk ke struktur FILE_OBJECT . Struktur ini disertakan dalam semua permintaan I/O yang dikirim driver ke target I/O (lihat WdfRequestGetFileObject). Anggota ini bersifat opsional dan dapat berupa NULL. Jika nilai Jenis bukan WdfIoTargetOpenUseExistingDevice, anggota ini diabaikan.

TargetDeviceName

Jika nilai Jenis adalah WdfIoTargetOpenByName, ini adalah struktur UNICODE_STRING yang berisi nama perangkat, file, atau antarmuka perangkat. Untuk informasi tentang format nama ini, lihat Nama Objek.

Jika nilai Jenis bukan WdfIoTargetOpenByName, anggota ini diabaikan.

DesiredAccess

Jika nilai Jenis adalah WdfIoTargetOpenByName, ini adalah nilai ACCESS_MASK .

Jika nilai Jenis bukan WdfIoTargetOpenByName, anggota ini diabaikan.

KMDF Nilai yang mungkin termasuk nilai FILE_Xxxx_ACCESS, seperti FILE_ANY_ACCESS, FILE_SPECIAL_ACCESS, FILE_READ_ACCESS, atau FILE_WRITE_ACCESS, serta GENERIC_READ, GENERIC_WRITE, dan GENERIC_ALL.

UMDF Nilai yang paling umum digunakan adalah GENERIC_READ, GENERIC_WRITE, atau keduanya (GENERIC_READ | GENERIC_WRITE). Perhatikan bahwa ACCESS_MASK adalah nilai DWORD. Untuk informasi selengkapnya tentang anggota ini, lihat parameter dwDesiredAccess dari CreateFile di Windows SDK.

ShareAccess

Jika nilai Jenis bukan WdfIoTargetOpenByName, anggota ini diabaikan.

KMDF Jika nilai Jenis adalah WdfIoTargetOpenByName, ini adalah bitwise ATAU dari bendera berikut (yang ditentukan dalam Wdm.h), atau nol.

Bendera ShareAccess	Makna
FILE_SHARE_READ	Pengandar tidak memerlukan akses baca eksklusif ke perangkat.
FILE_SHARE_WRITE	Pengandar tidak memerlukan akses tulis eksklusif ke perangkat.
FILE_SHARE_DELETE	Pengandar tidak memerlukan akses penghapusan eksklusif ke perangkat.

UMDF Untuk informasi selengkapnya tentang anggota ini, lihat parameter dwShareMode dari fungsi CreateFile di Windows SDK.

Nilai nol di ShareAccess menunjukkan bahwa driver memerlukan akses eksklusif ke perangkat.

FileAttributes

KMDF Jika nilai Jenis adalah WdfIoTargetOpenByName, ini adalah bitwise OR dari bendera FILE_ATTRIBUTE_Xxxx yang ditentukan dalam Wdm.h. Sebagian besar driver menentukan FILE_ATTRIBUTE_NORMAL. Untuk informasi selengkapnya tentang bendera ini, lihat ZwCreateFile.

UMDF Untuk informasi selengkapnya tentang anggota ini, lihat parameter dwFlagsAndAttributes dari fungsi CreateFile di Windows SDK.

Jika nilai Jenis bukan WdfIoTargetOpenByName, anggota ini diabaikan.

CreateDisposition

KMDF Jika nilai Jenis adalah WdfIoTargetOpenByName, nilai ini menunjukkan tindakan yang harus diambil sistem saat membuka file. Untuk daftar nilai yang mungkin, lihat ZwCreateFile.

UMDF Untuk informasi selengkapnya tentang anggota ini, lihat parameter dwCreationDisposition dari fungsi CreateFile di Windows SDK.

Jika nilai Jenis bukan WdfIoTargetOpenByName, anggota ini diabaikan.

CreateOptions

Anggota ini tidak berlaku untuk driver UMDF.

KMDF Jika nilai Jenis adalah WdfIoTargetOpenByName, ini adalah bitwise ATAU bendera opsi file. Untuk daftar bendera yang mungkin, lihat ZwCreateFile. Jika nilai Jenis bukan WdfIoTargetOpenByName, anggota ini diabaikan.

EaBuffer

Anggota ini tidak berlaku untuk driver UMDF.

KMDF Jika nilai Jenis adalah WdfIoTargetOpenByName, anggota ini menunjuk ke buffer atribut yang diperluas. Biasanya, driver menyediakan NULL untuk nilai ini. Jika nilai Jenis bukan WdfIoTargetOpenByName, anggota ini diabaikan.

EaBufferLength

Anggota ini tidak berlaku untuk driver UMDF.

KMDF Jika nilai Jenis adalah WdfIoTargetOpenByName, ini adalah panjang buffer atribut yang diperluas. Biasanya, driver menyediakan nol untuk nilai ini. Jika nilai Jenis bukan WdfIoTargetOpenByName, anggota ini diabaikan.

AllocationSize

Anggota ini tidak berlaku untuk driver UMDF.

KMDF Jika nilai Jenis adalah WdfIoTargetOpenByName, anggota ini menentukan ukuran, dalam byte, bahwa sistem awalnya harus mengalokasikan untuk file, jika membuat file baru. Nilai ini bersifat opsional dan bisa nol. Jika nilai Jenis bukan WdfIoTargetOpenByName, anggota ini diabaikan.

FileInformation

Anggota ini tidak berlaku untuk driver UMDF.

KMDF Jika nilai Jenis adalah WdfIoTargetOpenByName, anggota ini menerima informasi status saat panggilan ke WdfIoTargetOpen kembali. Informasinya adalah salah satu nilai berikut: FILE_CREATED, FILE_OPENED, FILE_OVERWRITTEN, FILE_SUPERSEDED, FILE_EXISTS, atau FILE_DOES_NOT_EXIST. Jika nilai Jenis bukan WdfIoTargetOpenByName, anggota ini diabaikan.

FileName

Anggota ini tidak berlaku untuk driver KMDF.

UMDF Struktur UNICODE_STRING yang berisi nama file untuk membuat objek file. Anggota ini bersifat opsional, dan hanya berlaku ketika nilai Jenis adalah WdfIoTargetOpenLocalTargetByFile. Sebagian besar driver menentukan NULL di sini kecuali target yang lebih rendah mendukung Akses Namespace Perangkat. Jika disediakan, string tidak boleh berisi karakter pemisah jalur apa pun (garis miring atau garis miring terbelakang).

Keterangan

Driver harus menginisialisasi struktur WDF_IO_TARGET_OPEN_PARAMS dengan memanggil salah satu fungsi berikut:

WDF_IO_TARGET_OPEN_PARAMS_INIT_EXISTING_DEVICE, jika driver Anda dapat mengidentifikasi perangkat target dengan menyediakan pointer ke struktur DEVICE_OBJECT .
WDF_IO_TARGET_OPEN_PARAMS_INIT_CREATE_BY_NAME, jika target I/O adalah perangkat, file, atau antarmuka perangkat, dan apakah driver Anda dapat memberikan nama perangkat, file, atau antarmuka perangkat. Jika Anda menentukan nama file yang sudah ada, sistem akan menggantikan file yang ada. Jika file tidak ada, sistem akan membuatnya.
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME, jika target I/O adalah perangkat, file, atau antarmuka perangkat, dan jika driver Anda dapat memberikan nama perangkat, file, atau antarmuka perangkat. Jika Anda menentukan nama file yang sudah ada, sistem akan membuka file yang ada. Jika file tidak ada, operasi buka gagal.
WDF_IO_TARGET_OPEN_PARAMS_INIT_REOPEN, jika fungsi panggilan balik EvtIoTargetRemoveCanceled driver Anda membuka kembali target I/O jarak jauh karena perangkat tidak dihapus.
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, jika driver UMDF Anda perlu mengirim permintaan yang dibuat driver ke target yang lebih rendah yang memerlukan objek file terkait.