WDF_IO_TARGET_OPEN_PARAMS 結構 (wdfiotarget.h)

[適用於 KMDF 和 UMDF]

WDF_IO_TARGET_OPEN_PARAMS 結構包含 WdfIoTargetOpen 方法所使用的參數。

語法

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;

成員

Size

這個結構的大小，以位元組為單位。

Type

WDF_IO_TARGET_OPEN_TYPE型別值，指出 WdfIoTargetOpen 將執行的開啟作業類型。

EvtIoTargetQueryRemove

驅動程式 EvtIoTargetQueryRemove 事件回呼函式或 NULL 的指標。

EvtIoTargetRemoveCanceled

驅動程式 EvtIoTargetRemoveCanceled 事件回呼函式或 NULL 的指標。

EvtIoTargetRemoveComplete

驅動程式 EvtIoTargetRemoveComplete 事件回呼函式或 NULL 的指標。

TargetDeviceObject

此成員不適用於 UMDF 驅動程式。

KMDF 如果 Type 的值是 WdfIoTargetOpenUseExistingDevice，這是代表 I/O 目標裝置之 DEVICE_OBJECT 結構的指標。 如果 Type 的值不是 WdfIoTargetOpenUseExistingDevice，則會忽略此成員。

TargetFileObject

此成員不適用於 UMDF 驅動程式。

KMDF 如果 Type 的值是 WdfIoTargetOpenUseExistingDevice，則這是 FILE_OBJECT 結構的指標。 此結構包含在驅動程式傳送至 I/O 目標的所有 I/O 要求中， (請參閱 WdfRequestGetFileObject) 。 此成員是選擇性的，可以是 NULL。 如果 Type 的值不是 WdfIoTargetOpenUseExistingDevice，則會忽略此成員。

TargetDeviceName

如果 Type 的值是 WdfIoTargetOpenByName，這是包含裝置、檔案或裝置介面名稱 的UNICODE_STRING 結構。 如需此名稱格式的詳細資訊，請參閱 物件名稱。

如果 Type 的值不是 WdfIoTargetOpenByName，則會忽略這個成員。

DesiredAccess

如果 Type 的值是 WdfIoTargetOpenByName，則這是 ACCESS_MASK 值。

如果 Type 的值不是 WdfIoTargetOpenByName，則會忽略這個成員。

KMDF 可能的值包括FILE_Xxxx_ACCESS值，例如FILE_ANY_ACCESS、FILE_SPECIAL_ACCESS、FILE_READ_ACCESS或FILE_WRITE_ACCESS，以及GENERIC_READ、GENERIC_WRITE和GENERIC_ALL。

UMDF 最常使用的值是GENERIC_READ、GENERIC_WRITE或兩者 (GENERIC_READ |GENERIC_WRITE) 。 請注意 ，ACCESS_MASK 是 DWORD 值。 如需此成員的詳細資訊，請參閱 Windows SDK 中 CreateFile 的 dwDesiredAccess 參數。

ShareAccess

如果 Type 的值不是 WdfIoTargetOpenByName，則會忽略這個成員。

KMDF 如果 Type 的值是 WdfIoTargetOpenByName，則這是下列旗標的位 OR， (定義於 Wdm.h) 或零。

ShareAccess 旗標	意義
FILE_SHARE_READ	驅動程式不需要裝置的獨佔讀取許可權。
FILE_SHARE_WRITE	驅動程式不需要裝置的獨佔寫入許可權。
FILE_SHARE_DELETE	驅動程式不需要對裝置進行獨佔刪除存取。

 

UMDF 如需此成員的詳細資訊，請參閱 Windows SDK 中 CreateFile 函式的 dwShareMode 參數。

ShareAccess 中的值為零，表示驅動程式需要裝置的獨佔存取權。

FileAttributes

KMDF 如果 Type 的值是 WdfIoTargetOpenByName，這是 Wdm.h 中所定義之FILE_ATTRIBUTE_Xxxx 旗標的位 OR。 大部分驅動程式都會指定FILE_ATTRIBUTE_NORMAL。 如需這些旗標的詳細資訊，請參閱 ZwCreateFile。

UMDF 如需此成員的詳細資訊，請參閱 Windows SDK 中 CreateFile 函式的 dwFlagsAndAttributes 參數。

如果 Type 的值不是 WdfIoTargetOpenByName，則會忽略這個成員。

CreateDisposition

KMDF 如果 Type 的值是 WdfIoTargetOpenByName，這個值表示開啟檔案時，系統要採取的動作。 如需可能值的清單，請參閱 ZwCreateFile。

UMDF 如需此成員的詳細資訊，請參閱 Windows SDK 中 CreateFile 函式的 dwCreationDisposition 參數。

如果 Type 的值不是 WdfIoTargetOpenByName，則會忽略這個成員。

CreateOptions

此成員不適用於 UMDF 驅動程式。

KMDF 如果 Type 的值是 WdfIoTargetOpenByName，則這是檔案選項旗標的位 OR。 如需可能旗標的清單，請參閱 ZwCreateFile。 如果 Type 的值不是 WdfIoTargetOpenByName，則會忽略這個成員。

EaBuffer

此成員不適用於 UMDF 驅動程式。

KMDF 如果 Type 的值是 WdfIoTargetOpenByName，則此成員會指向擴充屬性緩衝區。 一般而言，驅動程式會提供此值的 NULL 。 如果 Type 的值不是 WdfIoTargetOpenByName，則會忽略這個成員。

EaBufferLength

此成員不適用於 UMDF 驅動程式。

KMDF 如果 Type 的值是 WdfIoTargetOpenByName，則這是擴充屬性緩衝區的長度。 一般而言，驅動程式會提供此值的零。 如果 Type 的值不是 WdfIoTargetOpenByName，則會忽略這個成員。

AllocationSize

此成員不適用於 UMDF 驅動程式。

KMDF 如果 Type 的值是 WdfIoTargetOpenByName，則此成員會指定系統一開始應該為檔案配置的大小，如果是建立新的檔案，則此成員會指定大小。 這個值是選擇性的，而且可以是零。 如果 Type 的值不是 WdfIoTargetOpenByName，則會忽略這個成員。

FileInformation

此成員不適用於 UMDF 驅動程式。

KMDF 如果 Type 的值是 WdfIoTargetOpenByName，當呼叫 WdfIoTargetOpen 傳回時，此成員會收到狀態資訊。 此資訊是下列其中一個值：FILE_CREATED、FILE_OPENED、FILE_OVERWRITTEN、FILE_SUPERSEDED、FILE_EXISTS或FILE_DOES_NOT_EXIST。 如果 Type 的值不是 WdfIoTargetOpenByName，則會忽略這個成員。

FileName

此成員不適用於 KMDF 驅動程式。

UMDF 包含要建立檔案物件之檔名的UNICODE_STRING結構。 這個成員是選擇性的，而且只有在 Type 的值是 WdfIoTargetOpenLocalTargetByFile 時才適用。 除非較低的目標支援裝置命名空間存取，否則大部分驅動程式都會在這裡指定NULL。 如果提供，字串不得包含任何路徑分隔符， (正斜線或反斜杠) 。

備註

驅動程式應該藉由呼叫下列其中一個函式來初始化 WDF_IO_TARGET_OPEN_PARAMS 結構：

• WDF_IO_TARGET_OPEN_PARAMS_INIT_EXISTING_DEVICE，如果您的驅動程式可以藉由提供 DEVICE_OBJECT 結構的指標來識別目標裝置。

• WDF_IO_TARGET_OPEN_PARAMS_INIT_CREATE_BY_NAME，如果 I/O 目標是裝置、檔案或裝置介面，而且您的驅動程式可以提供裝置、檔案或裝置介面的名稱。 如果您指定已經存在的檔名，則系統會取代現有的檔案。 如果檔案不存在，系統會建立它。

• WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME，如果 I/O 目標是裝置、檔案或裝置介面，而且您的驅動程式可以提供裝置、檔案或裝置介面的名稱。 如果您指定已經存在的檔名，系統會開啟現有的檔案。 如果檔案不存在，開啟作業就會失敗。

• WDF_IO_TARGET_OPEN_PARAMS_INIT_REOPEN，如果驅動程式的 EvtIoTargetRemoveCanceled 回呼函式重新開啟遠端 I/O 目標，因為裝置並未移除。

• WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE，如果您的 UMDF 驅動程式必須將驅動程式建立的要求傳送至需要相關聯檔案物件的較低目標。

規格需求

需求	值
最小 KMDF 版本	1.0
最低UMDF版本	2.0
標頭	wdfiotarget.h (包含 Wdf.h)

另請參閱

ACCESS_MASK

DEVICE_OBJECT

EvtIoTargetQueryRemove

EvtIoTargetRemoveCanceled

FILE_OBJECT

UNICODE_STRING

WDF_IO_TARGET_OPEN_TYPE

WdfIoTargetOpen

WdfRequestGetFileObject

ZwCreateFile