estructura WDF_IO_TARGET_OPEN_PARAMS (wdfiotarget.h)

Artículo
02/27/2024

[Se aplica a KMDF y UMDF]

La estructura WDF_IO_TARGET_OPEN_PARAMS contiene parámetros que usa el método WdfIoTargetOpen .

Sintaxis

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;

Miembros

Size

Tamaño, en bytes, de esta estructura.

Type

Valor con tipo WDF_IO_TARGET_OPEN_TYPE, que indica el tipo de operación abierta que realizará WdfIoTargetOpen .

EvtIoTargetQueryRemove

Puntero a la función de devolución de llamada de eventos EvtIoTargetQueryRemove del controlador o NULL.

EvtIoTargetRemoveCanceled

Puntero a la función de devolución de llamada de eventos EvtIoTargetRemoveCanceled del controlador o NULL.

EvtIoTargetRemoveComplete

Puntero a la función de devolución de llamada de eventos EvtIoTargetRemoveComplete del controlador o NULL.

TargetDeviceObject

Este miembro no es aplicable a los controladores UMDF.

KMDF Si el valor de Type es WdfIoTargetOpenUseExistingDevice, se trata de un puntero a una estructura de DEVICE_OBJECT que representa el dispositivo del destino de E/S. Si el valor de Type no es WdfIoTargetOpenUseExistingDevice, este miembro se omite.

TargetFileObject

Este miembro no es aplicable a los controladores UMDF.

KMDF Si el valor de Type es WdfIoTargetOpenUseExistingDevice, se trata de un puntero a una estructura FILE_OBJECT . Esta estructura se incluye en todas las solicitudes de E/S que el controlador envía al destino de E/S (consulte WdfRequestGetFileObject). Este miembro es opcional y puede ser NULL. Si el valor de Type no es WdfIoTargetOpenUseExistingDevice, este miembro se omite.

TargetDeviceName

Si el valor de Type es WdfIoTargetOpenByName, se trata de una estructura de UNICODE_STRING que contiene el nombre de un dispositivo, un archivo o una interfaz de dispositivo. Para obtener información sobre el formato de este nombre, vea Nombres de objeto.

Si el valor de Type no es WdfIoTargetOpenByName, este miembro se omite.

DesiredAccess

Si el valor de Type es WdfIoTargetOpenByName, se trata de un valor de ACCESS_MASK .

Si el valor de Type no es WdfIoTargetOpenByName, este miembro se omite.

KMDF Entre los valores posibles se incluyen FILE_Xxxx_ACCESS valores, como FILE_ANY_ACCESS, FILE_SPECIAL_ACCESS, FILE_READ_ACCESS o FILE_WRITE_ACCESS, así como GENERIC_READ, GENERIC_WRITE y GENERIC_ALL.

UMDF Los valores más usados son GENERIC_READ, GENERIC_WRITE o ambos (GENERIC_READ | GENERIC_WRITE). Tenga en cuenta que ACCESS_MASK es un valor DWORD. Para obtener más información sobre este miembro, vea el parámetro dwDesiredAccess de CreateFile en Windows SDK.

ShareAccess

Si el valor de Type no es WdfIoTargetOpenByName, este miembro se omite.

KMDF Si el valor de Type es WdfIoTargetOpenByName, se trata de un OR bit a bit de las marcas siguientes (que se definen en Wdm.h) o cero.

Marca de ShareAccess	Significado
FILE_SHARE_READ	El controlador no requiere acceso de lectura exclusivo al dispositivo.
FILE_SHARE_WRITE	El controlador no requiere acceso exclusivo de escritura al dispositivo.
FILE_SHARE_DELETE	El controlador no requiere acceso exclusivo de eliminación al dispositivo.

UMDF Para obtener más información sobre este miembro, vea el parámetro dwShareMode de la función CreateFile en Windows SDK.

Un valor de cero en ShareAccess indica que el controlador requiere acceso exclusivo al dispositivo.

FileAttributes

KMDF Si el valor de Type es WdfIoTargetOpenByName, se trata de un OR bit a bit de las marcas FILE_ATTRIBUTE_Xxxx definidas en Wdm.h. La mayoría de los controladores especifican FILE_ATTRIBUTE_NORMAL. Para obtener más información sobre estas marcas, vea ZwCreateFile.

UMDF Para obtener más información sobre este miembro, vea el parámetro dwFlagsAndAttributes de la función CreateFile en Windows SDK.

Si el valor de Type no es WdfIoTargetOpenByName, este miembro se omite.

CreateDisposition

KMDF Si el valor de Type es WdfIoTargetOpenByName, este valor indica una acción para que el sistema realice al abrir un archivo. Para obtener una lista de los valores posibles, consulte ZwCreateFile.

UMDF Para obtener más información sobre este miembro, vea el parámetro dwCreationDisposition de la función CreateFile en Windows SDK.

Si el valor de Type no es WdfIoTargetOpenByName, este miembro se omite.

CreateOptions

Este miembro no es aplicable a los controladores UMDF.

KMDF Si el valor de Type es WdfIoTargetOpenByName, se trata de un OR bit a bit de marcas de opción de archivo. Para obtener una lista de posibles marcas, consulte ZwCreateFile. Si el valor de Type no es WdfIoTargetOpenByName, este miembro se omite.

EaBuffer

Este miembro no es aplicable a los controladores UMDF.

KMDF Si el valor de Type es WdfIoTargetOpenByName, este miembro apunta a un búfer de atributos extendidos. Normalmente, los controladores proporcionan NULL para este valor. Si el valor de Type no es WdfIoTargetOpenByName, este miembro se omite.

EaBufferLength

Este miembro no es aplicable a los controladores UMDF.

KMDF Si el valor de Type es WdfIoTargetOpenByName, esta es la longitud del búfer de atributos extendidos. Normalmente, los controladores proporcionan cero para este valor. Si el valor de Type no es WdfIoTargetOpenByName, este miembro se omite.

AllocationSize

Este miembro no es aplicable a los controladores UMDF.

KMDF Si el valor de Type es WdfIoTargetOpenByName, este miembro especifica el tamaño, en bytes, que el sistema debe asignar inicialmente para el archivo, si está creando un nuevo archivo. Este valor es opcional y puede ser cero. Si el valor de Type no es WdfIoTargetOpenByName, este miembro se omite.

FileInformation

Este miembro no es aplicable a los controladores UMDF.

KMDF Si el valor de Type es WdfIoTargetOpenByName, este miembro recibe información de estado cuando la llamada a WdfIoTargetOpen devuelve. La información es uno de los siguientes valores: FILE_CREATED, FILE_OPENED, FILE_OVERWRITTEN, FILE_SUPERSEDED, FILE_EXISTS o FILE_DOES_NOT_EXIST. Si el valor de Type no es WdfIoTargetOpenByName, este miembro se omite.

FileName

Este miembro no es aplicable a los controladores KMDF.

UMDF Estructura UNICODE_STRING que contiene el nombre del archivo desde el que se va a crear un objeto de archivo. Este miembro es opcional y solo es aplicable cuando el valor de Type es WdfIoTargetOpenLocalTargetByFile. La mayoría de los controladores especifican NULL aquí, a menos que el destino inferior admita el acceso al espacio de nombres de dispositivo. Si se proporciona, la cadena no debe contener caracteres separadores de ruta de acceso (barra diagonal o barra diagonal inversa).

Comentarios

Los controladores deben inicializar la estructura de WDF_IO_TARGET_OPEN_PARAMS llamando a una de las funciones siguientes:

WDF_IO_TARGET_OPEN_PARAMS_INIT_EXISTING_DEVICE, si el controlador puede identificar un dispositivo de destino proporcionando un puntero a una estructura de DEVICE_OBJECT .
WDF_IO_TARGET_OPEN_PARAMS_INIT_CREATE_BY_NAME, si el destino de E/S es un dispositivo, un archivo o una interfaz de dispositivo, y si el controlador puede proporcionar el nombre del dispositivo, el archivo o la interfaz del dispositivo. Si especifica el nombre de un archivo que ya existe, el sistema reemplaza el archivo existente. Si el archivo no existe, el sistema lo crea.
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME, si el destino de E/S es un dispositivo, un archivo o una interfaz de dispositivo, y si el controlador puede proporcionar el nombre del dispositivo, el archivo o la interfaz del dispositivo. Si especifica el nombre de un archivo que ya existe, el sistema abre el archivo existente. Si el archivo no existe, se produce un error en la operación de apertura.
WDF_IO_TARGET_OPEN_PARAMS_INIT_REOPEN, si la función de devolución de llamada EvtIoTargetRemoveCanceled del controlador vuelve a abrir un destino de E/S remoto porque el dispositivo no se quitó.
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, si el controlador UMDF necesita enviar solicitudes creadas por controladores para reducir los destinos que requieren un objeto de archivo asociado.