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