struttura WDF_IO_TARGET_OPEN_PARAMS (wdfiotarget.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

La struttura WDF_IO_TARGET_OPEN_PARAMS contiene parametri usati dal metodo WdfIoTargetOpen .

Sintassi

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

Dimensione, in byte, della struttura.

Type

Valore tipizzato WDF_IO_TARGET_OPEN_TYPE, che indica il tipo di operazione aperta eseguita da WdfIoTargetOpen .

EvtIoTargetQueryRemove

Puntatore alla funzione di callback dell'evento EvtIoTargetQueryRemove del driver o NULL.

EvtIoTargetRemoveCanceled

Puntatore alla funzione di callback dell'evento EvtIoTargetRemoveCanceled del driver o NULL.

EvtIoTargetRemoveComplete

Puntatore alla funzione di callback dell'evento EvtIoTargetRemoveComplete del driver o NULL.

TargetDeviceObject

Questo membro non è applicabile ai driver UMDF.

KMDF Se il valore di Type è WdfIoTargetOpenUseExistingDevice, si tratta di un puntatore a una struttura DEVICE_OBJECT che rappresenta il dispositivo di destinazione I/O. Se il valore di Type non è WdfIoTargetOpenUseExistingDevice, questo membro viene ignorato.

TargetFileObject

Questo membro non è applicabile ai driver UMDF.

KMDF Se il valore di Type è WdfIoTargetOpenUseExistingDevice, si tratta di un puntatore a una struttura FILE_OBJECT . Questa struttura è inclusa in tutte le richieste di I/O inviate dal driver alla destinazione di I/O (vedere WdfRequestGetFileObject). Questo membro è facoltativo e può essere NULL. Se il valore di Type non è WdfIoTargetOpenUseExistingDevice, questo membro viene ignorato.

TargetDeviceName

Se il valore di Type è WdfIoTargetOpenByName, si tratta di una struttura UNICODE_STRING che contiene il nome di un dispositivo, di un file o di un'interfaccia del dispositivo. Per informazioni sul formato di questo nome, vedere Nomi di oggetti.

Se il valore di Type non è WdfIoTargetOpenByName, questo membro viene ignorato.

DesiredAccess

Se il valore di Type è WdfIoTargetOpenByName, si tratta di un valore ACCESS_MASK .

Se il valore di Type non è WdfIoTargetOpenByName, questo membro viene ignorato.

KMDF I valori possibili includono valori FILE_Xxxx_ACCESS, ad esempio FILE_ANY_ACCESS, FILE_SPECIAL_ACCESS, FILE_READ_ACCESS o FILE_WRITE_ACCESS, nonché GENERIC_READ, GENERIC_WRITE e GENERIC_ALL.

UMDF I valori più usati sono GENERIC_READ, GENERIC_WRITE o entrambi (GENERIC_READ | GENERIC_WRITE). Si noti che ACCESS_MASK è un valore DWORD. Per altre informazioni su questo membro, vedere il parametro dwDesiredAccess di CreateFile in Windows SDK.

ShareAccess

Se il valore di Type non è WdfIoTargetOpenByName, questo membro viene ignorato.

KMDF Se il valore di Type è WdfIoTargetOpenByName, si tratta di un OR bit per bit dei flag seguenti (definiti in Wdm.h) o zero.

Flag ShareAccess	Significato
FILE_SHARE_READ	Il driver non richiede l'accesso in lettura esclusivo al dispositivo.
FILE_SHARE_WRITE	Il driver non richiede l'accesso in scrittura esclusivo al dispositivo.
FILE_SHARE_DELETE	Il driver non richiede l'accesso esclusivo all'eliminazione al dispositivo.

UMDF Per altre informazioni su questo membro, vedere il parametro dwShareMode della funzione CreateFile in Windows SDK.

Un valore pari a zero in ShareAccess indica che il driver richiede l'accesso esclusivo al dispositivo.

FileAttributes

KMDF Se il valore di Type è WdfIoTargetOpenByName, si tratta di un OR bit per bit dei flag FILE_ATTRIBUTE_Xxxx definiti in Wdm.h. La maggior parte dei driver specifica FILE_ATTRIBUTE_NORMAL. Per altre informazioni su questi flag, vedere ZwCreateFile.

UMDF Per altre informazioni su questo membro, vedere il parametro dwFlagsAndAttributes della funzione CreateFile in Windows SDK.

Se il valore di Type non è WdfIoTargetOpenByName, questo membro viene ignorato.

CreateDisposition

KMDF Se il valore di Type è WdfIoTargetOpenByName, questo valore indica un'azione che il sistema deve eseguire all'apertura di un file. Per un elenco dei valori possibili, vedere ZwCreateFile.

UMDF Per altre informazioni su questo membro, vedere il parametro dwCreationDisposition della funzione CreateFile in Windows SDK.

Se il valore di Type non è WdfIoTargetOpenByName, questo membro viene ignorato.

CreateOptions

Questo membro non è applicabile ai driver UMDF.

KMDF Se il valore di Type è WdfIoTargetOpenByName, si tratta di un OR bit per bit dei flag di opzione di file. Per un elenco dei flag possibili, vedere ZwCreateFile. Se il valore di Type non è WdfIoTargetOpenByName, questo membro viene ignorato.

EaBuffer

Questo membro non è applicabile ai driver UMDF.

KMDF Se il valore di Type è WdfIoTargetOpenByName, questo membro punta a un buffer di attributi estesi. In genere, i driver forniscono NULL per questo valore. Se il valore di Type non è WdfIoTargetOpenByName, questo membro viene ignorato.

EaBufferLength

Questo membro non è applicabile ai driver UMDF.

KMDF Se il valore di Type è WdfIoTargetOpenByName, si tratta della lunghezza del buffer degli attributi estesi. In genere, i driver forniscono zero per questo valore. Se il valore di Type non è WdfIoTargetOpenByName, questo membro viene ignorato.

AllocationSize

Questo membro non è applicabile ai driver UMDF.

KMDF Se il valore di Type è WdfIoTargetOpenByName, questo membro specifica le dimensioni, in byte, che il sistema deve allocare inizialmente per il file, se sta creando un nuovo file. Questo valore è facoltativo e può essere zero. Se il valore di Type non è WdfIoTargetOpenByName, questo membro viene ignorato.

FileInformation

Questo membro non è applicabile ai driver UMDF.

KMDF Se il valore di Type è WdfIoTargetOpenByName, questo membro riceve informazioni sullo stato quando viene restituita la chiamata a WdfIoTargetOpen . Le informazioni sono uno dei valori seguenti: FILE_CREATED, FILE_OPENED, FILE_OVERWRITTEN, FILE_SUPERSEDED, FILE_EXISTS o FILE_DOES_NOT_EXIST. Se il valore di Type non è WdfIoTargetOpenByName, questo membro viene ignorato.

FileName

Questo membro non è applicabile ai driver KMDF.

UMDF Struttura UNICODE_STRING che contiene il nome del file da cui creare un oggetto file. Questo membro è facoltativo ed è applicabile solo quando il valore di Type è WdfIoTargetOpenLocalTargetByFile. La maggior parte dei driver specifica qui NULL , a meno che la destinazione inferiore non supporti l'accesso allo spazio dei nomi dei dispositivi. Se specificato, la stringa non deve contenere caratteri separatori di percorso (barra o barra rovesciata).

Commenti

I driver devono inizializzare la struttura WDF_IO_TARGET_OPEN_PARAMS chiamando una delle funzioni seguenti:

WDF_IO_TARGET_OPEN_PARAMS_INIT_EXISTING_DEVICE, se il driver può identificare un dispositivo di destinazione fornendo un puntatore a una struttura di DEVICE_OBJECT .
WDF_IO_TARGET_OPEN_PARAMS_INIT_CREATE_BY_NAME, se la destinazione di I/O è un dispositivo, un file o un'interfaccia del dispositivo e se il driver può specificare il nome del dispositivo, del file o dell'interfaccia del dispositivo. Se si specifica il nome di un file già esistente, il sistema sostituisce il file esistente. Se il file non esiste, il sistema lo crea.
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME, se la destinazione di I/O è un dispositivo, un file o un'interfaccia del dispositivo e se il driver può fornire il nome del dispositivo, del file o dell'interfaccia del dispositivo. Se si specifica il nome di un file già esistente, il sistema apre il file esistente. Se il file non esiste, l'operazione di apertura ha esito negativo.
WDF_IO_TARGET_OPEN_PARAMS_INIT_REOPEN, se la funzione di callback EvtIoTargetRemoveCanceled del driver riapre una destinazione di I/O remota perché il dispositivo non è stato rimosso.
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, se il driver UMDF deve inviare richieste create dal driver a destinazioni inferiori che richiedono un oggetto file associato.