WDF_IO_TARGET_OPEN_PARAMS structure (wdfiotarget.h)
[Applies to KMDF and UMDF]
The WDF_IO_TARGET_OPEN_PARAMS structure contains parameters that the WdfIoTargetOpen method uses.
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;
Members
Size
The size, in bytes, of this structure.
Type
A WDF_IO_TARGET_OPEN_TYPE-typed value, which indicates the type of open operation that WdfIoTargetOpen will perform.
EvtIoTargetQueryRemove
A pointer to the driver's EvtIoTargetQueryRemove event callback function, or NULL.
EvtIoTargetRemoveCanceled
A pointer to the driver's EvtIoTargetRemoveCanceled event callback function, or NULL.
EvtIoTargetRemoveComplete
A pointer to the driver's EvtIoTargetRemoveComplete event callback function, or NULL.
TargetDeviceObject
This member is not applicable to UMDF drivers.
KMDF If the value of Type is WdfIoTargetOpenUseExistingDevice, this is a pointer to a DEVICE_OBJECT structure that represents the I/O target's device. If the value of Type is not WdfIoTargetOpenUseExistingDevice, this member is ignored.
TargetFileObject
This member is not applicable to UMDF drivers.
KMDF If the value of Type is WdfIoTargetOpenUseExistingDevice, this is a pointer to a FILE_OBJECT structure. This structure is included in all of the I/O requests that the driver sends to the I/O target (see WdfRequestGetFileObject). This member is optional and can be NULL. If the value of Type is not WdfIoTargetOpenUseExistingDevice, this member is ignored.
TargetDeviceName
If the value of Type is WdfIoTargetOpenByName, this is a UNICODE_STRING structure that contains the name of a device, file, or device interface. For information about the format of this name, see Object Names.
If the value of Type is not WdfIoTargetOpenByName, this member is ignored.
DesiredAccess
If the value of Type is WdfIoTargetOpenByName, this is an ACCESS_MASK value.
If the value of Type is not WdfIoTargetOpenByName, this member is ignored.
KMDF Possible values include FILE_Xxxx_ACCESS values, such as FILE_ANY_ACCESS, FILE_SPECIAL_ACCESS, FILE_READ_ACCESS, or FILE_WRITE_ACCESS, as well as GENERIC_READ, GENERIC_WRITE, and GENERIC_ALL.
UMDF The most commonly used values are GENERIC_READ, GENERIC_WRITE, or both (GENERIC_READ | GENERIC_WRITE). Note that ACCESS_MASK is a DWORD value. For more information about this member, see the dwDesiredAccess parameter of CreateFile in the Windows SDK.
ShareAccess
If the value of Type is not WdfIoTargetOpenByName, this member is ignored.
KMDF If the value of Type is WdfIoTargetOpenByName, this is a bitwise OR of the following flags (which are defined in Wdm.h), or zero.
| ShareAccess flag | Meaning |
|---|---|
| FILE_SHARE_READ | The driver does not require exclusive read access to the device. |
| FILE_SHARE_WRITE | The driver does not require exclusive write access to the device. |
| FILE_SHARE_DELETE | The driver does not require exclusive delete access to the device. |
UMDF For more information about this member, see the dwShareMode parameter of the CreateFile function in the Windows SDK.
A value of zero in ShareAccess indicates that the driver requires exclusive access to the device.
FileAttributes
KMDF If the value of Type is WdfIoTargetOpenByName, this is a bitwise OR of the FILE_ATTRIBUTE_Xxxx flags that are defined in Wdm.h. Most drivers specify FILE_ATTRIBUTE_NORMAL. For more information about these flags, see ZwCreateFile.
UMDF For more information about this member, see the dwFlagsAndAttributes parameter of the CreateFile function in the Windows SDK.
If the value of Type is not WdfIoTargetOpenByName, this member is ignored.
CreateDisposition
KMDF If the value of Type is WdfIoTargetOpenByName, this value indicates an action for the system to take when opening a file. For a list of possible values, see ZwCreateFile.
UMDF For more information about this member, see the dwCreationDisposition parameter of the CreateFile function in the Windows SDK.
If the value of Type is not WdfIoTargetOpenByName, this member is ignored.
CreateOptions
This member is not applicable to UMDF drivers.
KMDF If the value of Type is WdfIoTargetOpenByName, this is a bitwise OR of file option flags. For a list of possible flags, see ZwCreateFile. If the value of Type is not WdfIoTargetOpenByName, this member is ignored.
EaBuffer
This member is not applicable to UMDF drivers.
KMDF If the value of Type is WdfIoTargetOpenByName, this member points to an extended attributes buffer. Typically, drivers supply NULL for this value. If the value of Type is not WdfIoTargetOpenByName, this member is ignored.
EaBufferLength
This member is not applicable to UMDF drivers.
KMDF If the value of Type is WdfIoTargetOpenByName, this is the length of the extended attributes buffer. Typically, drivers supply zero for this value. If the value of Type is not WdfIoTargetOpenByName, this member is ignored.
AllocationSize
This member is not applicable to UMDF drivers.
KMDF If the value of Type is WdfIoTargetOpenByName, this member specifies the size, in bytes, that the system should initially allocate for the file, if it is creating a new file. This value is optional and can be zero. If the value of Type is not WdfIoTargetOpenByName, this member is ignored.
FileInformation
This member is not applicable to UMDF drivers.
KMDF If the value of Type is WdfIoTargetOpenByName, this member receives status information when the call to WdfIoTargetOpen returns. The information is one of the following values: FILE_CREATED, FILE_OPENED, FILE_OVERWRITTEN, FILE_SUPERSEDED, FILE_EXISTS, or FILE_DOES_NOT_EXIST. If the value of Type is not WdfIoTargetOpenByName, this member is ignored.
FileName
This member is not applicable to KMDF drivers.
UMDF A UNICODE_STRING structure that contains the name of the file from which to create a file object. This member is optional, and is applicable only when the value of Type is WdfIoTargetOpenLocalTargetByFile. Most drivers specify NULL here unless the lower target supports Device Namespace Access. If supplied, the string must not contain any path separator characters (forward slash or backslash).
Remarks
Drivers should initialize the WDF_IO_TARGET_OPEN_PARAMS structure by calling one of the following functions:
-
WDF_IO_TARGET_OPEN_PARAMS_INIT_EXISTING_DEVICE, if your driver can identify a target device by supplying a pointer to a DEVICE_OBJECT structure.
-
WDF_IO_TARGET_OPEN_PARAMS_INIT_CREATE_BY_NAME, if the I/O target is a device, file, or device interface, and if your driver can supply the name of the device, file, or device interface. If you specify the name of a file that already exists, the system replaces the existing file. If the file does not exist, the system creates it.
-
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME, if the I/O target is a device, file, or device interface, and if your driver can supply the name of the device, file, or device interface. If you specify the name of a file that already exists, the system opens the existing file. If the file does not exist, the open operation fails.
-
WDF_IO_TARGET_OPEN_PARAMS_INIT_REOPEN, if your driver's EvtIoTargetRemoveCanceled callback function is reopening a remote I/O target because the device was not removed.
-
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, if your UMDF driver needs to send driver-created requests to lower targets that require an associated file object.
Requirements
| Requirement | Value |
|---|---|
| Minimum KMDF version | 1.0 |
| Minimum UMDF version | 2.0 |
| Header | wdfiotarget.h (include Wdf.h) |