estrutura WDF_IO_TARGET_OPEN_PARAMS (wdfiotarget.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

A estrutura WDF_IO_TARGET_OPEN_PARAMS contém parâmetros que o método WdfIoTargetOpen usa.

Sintaxe

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;

Membros

Size

O tamanho, em bytes, dessa estrutura.

Type

Um valor do tipo WDF_IO_TARGET_OPEN_TYPE, que indica o tipo de operação aberta que WdfIoTargetOpen executará.

EvtIoTargetQueryRemove

Um ponteiro para a função de retorno de chamada de evento EvtIoTargetQueryRemove do driver ou NULL.

EvtIoTargetRemoveCanceled

Um ponteiro para a função de retorno de chamada de evento EvtIoTargetRemoveCanceled do driver ou NULL.

EvtIoTargetRemoveComplete

Um ponteiro para a função de retorno de chamada de evento EvtIoTargetRemoveComplete do driver ou NULL.

TargetDeviceObject

Esse membro não é aplicável aos drivers UMDF.

KMDF Se o valor de Type for WdfIoTargetOpenUseExistingDevice, esse será um ponteiro para uma estrutura DEVICE_OBJECT que representa o dispositivo do destino de E/S. Se o valor de Type não for WdfIoTargetOpenUseExistingDevice, esse membro será ignorado.

TargetFileObject

Esse membro não é aplicável aos drivers UMDF.

KMDF Se o valor de Type for WdfIoTargetOpenUseExistingDevice, esse será um ponteiro para uma estrutura FILE_OBJECT . Essa estrutura está incluída em todas as solicitações de E/S que o driver envia para o destino de E/S (consulte WdfRequestGetFileObject). Esse membro é opcional e pode ser NULL. Se o valor de Type não for WdfIoTargetOpenUseExistingDevice, esse membro será ignorado.

TargetDeviceName

Se o valor de Type for WdfIoTargetOpenByName, essa será uma estrutura UNICODE_STRING que contém o nome de um dispositivo, arquivo ou interface do dispositivo. Para obter informações sobre o formato desse nome, consulte Nomes de objeto.

Se o valor de Type não for WdfIoTargetOpenByName, esse membro será ignorado.

DesiredAccess

Se o valor de Type for WdfIoTargetOpenByName, esse será um valor ACCESS_MASK .

Se o valor de Type não for WdfIoTargetOpenByName, esse membro será ignorado.

KMDF Os valores possíveis incluem valores FILE_Xxxx_ACCESS, como FILE_ANY_ACCESS, FILE_SPECIAL_ACCESS, FILE_READ_ACCESS ou FILE_WRITE_ACCESS, bem como GENERIC_READ, GENERIC_WRITE e GENERIC_ALL.

UMDF Os valores mais usados são GENERIC_READ, GENERIC_WRITE ou ambos (GENERIC_READ | GENERIC_WRITE). Observe que ACCESS_MASK é um valor DWORD. Para obter mais informações sobre esse membro, consulte o parâmetro dwDesiredAccess de CreateFile no SDK do Windows.

ShareAccess

Se o valor de Type não for WdfIoTargetOpenByName, esse membro será ignorado.

KMDF Se o valor de Type for WdfIoTargetOpenByName, este será um OR bit a bit dos sinalizadores a seguir (que são definidos em Wdm.h) ou zero.

Sinalizador ShareAccess	Significado
FILE_SHARE_READ	O driver não requer acesso de leitura exclusivo ao dispositivo.
FILE_SHARE_WRITE	O driver não requer acesso de gravação exclusivo ao dispositivo.
FILE_SHARE_DELETE	O driver não requer acesso exclusivo de exclusão ao dispositivo.

UMDF Para obter mais informações sobre esse membro, consulte o parâmetro dwShareMode da função CreateFile no SDK do Windows.

Um valor zero no ShareAccess indica que o driver requer acesso exclusivo ao dispositivo.

FileAttributes

KMDF Se o valor de Type for WdfIoTargetOpenByName, esse será um OR bit a bit dos sinalizadores FILE_ATTRIBUTE_Xxxx definidos em Wdm.h. A maioria dos drivers especifica FILE_ATTRIBUTE_NORMAL. Para obter mais informações sobre esses sinalizadores, consulte ZwCreateFile.

UMDF Para obter mais informações sobre esse membro, consulte o parâmetro dwFlagsAndAttributes da função CreateFile no SDK do Windows.

Se o valor de Type não for WdfIoTargetOpenByName, esse membro será ignorado.

CreateDisposition

KMDF Se o valor de Type for WdfIoTargetOpenByName, esse valor indicará uma ação para o sistema tomar ao abrir um arquivo. Para obter uma lista de valores possíveis, consulte ZwCreateFile.

UMDF Para obter mais informações sobre esse membro, consulte o parâmetro dwCreationDisposition da função CreateFile no SDK do Windows.

Se o valor de Type não for WdfIoTargetOpenByName, esse membro será ignorado.

CreateOptions

Esse membro não é aplicável aos drivers UMDF.

KMDF Se o valor de Type for WdfIoTargetOpenByName, esse será um OR bit a bit dos sinalizadores de opção de arquivo. Para obter uma lista de sinalizadores possíveis, consulte ZwCreateFile. Se o valor de Type não for WdfIoTargetOpenByName, esse membro será ignorado.

EaBuffer

Esse membro não é aplicável aos drivers UMDF.

KMDF Se o valor de Type for WdfIoTargetOpenByName, esse membro apontará para um buffer de atributos estendidos. Normalmente, os drivers fornecem NULL para esse valor. Se o valor de Type não for WdfIoTargetOpenByName, esse membro será ignorado.

EaBufferLength

Esse membro não é aplicável aos drivers UMDF.

KMDF Se o valor de Type for WdfIoTargetOpenByName, esse será o comprimento do buffer de atributos estendidos. Normalmente, os drivers fornecem zero para esse valor. Se o valor de Type não for WdfIoTargetOpenByName, esse membro será ignorado.

AllocationSize

Esse membro não é aplicável aos drivers UMDF.

KMDF Se o valor de Type for WdfIoTargetOpenByName, esse membro especificará o tamanho, em bytes, que o sistema deve alocar inicialmente para o arquivo, se estiver criando um novo arquivo. Esse valor é opcional e pode ser zero. Se o valor de Type não for WdfIoTargetOpenByName, esse membro será ignorado.

FileInformation

Esse membro não é aplicável aos drivers UMDF.

KMDF Se o valor de Type for WdfIoTargetOpenByName, esse membro receberá status informações quando a chamada para WdfIoTargetOpen retornar. As informações são um dos seguintes valores: FILE_CREATED, FILE_OPENED, FILE_OVERWRITTEN, FILE_SUPERSEDED, FILE_EXISTS ou FILE_DOES_NOT_EXIST. Se o valor de Type não for WdfIoTargetOpenByName, esse membro será ignorado.

FileName

Esse membro não é aplicável a drivers KMDF.

UMDF Uma estrutura UNICODE_STRING que contém o nome do arquivo do qual criar um objeto de arquivo. Esse membro é opcional e é aplicável somente quando o valor de Type é WdfIoTargetOpenLocalTargetByFile. A maioria dos drivers especifica NULL aqui, a menos que o destino inferior dê suporte ao Acesso ao Namespace do Dispositivo. Se fornecida, a cadeia de caracteres não deve conter nenhum caractere separador de caminho (barra ou barra invertida).

Comentários

Os drivers devem inicializar a estrutura WDF_IO_TARGET_OPEN_PARAMS chamando uma das seguintes funções:

WDF_IO_TARGET_OPEN_PARAMS_INIT_EXISTING_DEVICE, se o driver puder identificar um dispositivo de destino fornecendo um ponteiro para uma estrutura DEVICE_OBJECT .
WDF_IO_TARGET_OPEN_PARAMS_INIT_CREATE_BY_NAME, se o destino de E/S for um dispositivo, arquivo ou interface do dispositivo e se o driver puder fornecer o nome do dispositivo, arquivo ou interface do dispositivo. Se você especificar o nome de um arquivo que já existe, o sistema substituirá o arquivo existente. Se o arquivo não existir, o sistema o criará.
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME, se o destino de E/S for um dispositivo, arquivo ou interface do dispositivo e se o driver puder fornecer o nome do dispositivo, arquivo ou interface do dispositivo. Se você especificar o nome de um arquivo que já existe, o sistema abrirá o arquivo existente. Se o arquivo não existir, a operação aberta falhará.
WDF_IO_TARGET_OPEN_PARAMS_INIT_REOPEN, se a função de retorno de chamada EvtIoTargetRemoveCanceled do driver estiver reabrindo um destino de E/S remoto porque o dispositivo não foi removido.
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, se o driver UMDF precisar enviar solicitações criadas pelo driver para destinos inferiores que exigem um objeto de arquivo associado.