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.

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

See also

ACCESS_MASK

DEVICE_OBJECT

EvtIoTargetQueryRemove

EvtIoTargetRemoveCanceled

FILE_OBJECT

UNICODE_STRING

WDF_IO_TARGET_OPEN_TYPE

WdfIoTargetOpen

WdfRequestGetFileObject

ZwCreateFile