WDF_IO_TARGET_OPEN_PARAMS structure (wdfiotarget.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La structure WDF_IO_TARGET_OPEN_PARAMS contient les paramètres utilisés par la méthode WdfIoTargetOpen .

Syntaxe

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;

Membres

Size

Taille, en octets, de cette structure.

Type

Valeur de type WDF_IO_TARGET_OPEN_TYPE, qui indique le type d’opération d’ouverture que WdfIoTargetOpen effectuera.

EvtIoTargetQueryRemove

Pointeur vers la fonction de rappel d’événement EvtIoTargetQueryRemove du pilote, ou NULL.

EvtIoTargetRemoveCanceled

Pointeur vers la fonction de rappel d’événement EvtIoTargetRemoveCanceled du pilote, ou NULL.

EvtIoTargetRemoveComplete

Pointeur vers la fonction de rappel d’événement EvtIoTargetRemoveComplete du pilote, ou NULL.

TargetDeviceObject

Ce membre n’est pas applicable aux pilotes UMDF.

KMDF Si la valeur de Type est WdfIoTargetOpenUseExistingDevice, il s’agit d’un pointeur vers une structure DEVICE_OBJECT qui représente l’appareil de la cible d’E/S. Si la valeur de Type n’est pas WdfIoTargetOpenUseExistingDevice, ce membre est ignoré.

TargetFileObject

Ce membre n’est pas applicable aux pilotes UMDF.

KMDF Si la valeur de Type est WdfIoTargetOpenUseExistingDevice, il s’agit d’un pointeur vers une structure FILE_OBJECT . Cette structure est incluse dans toutes les demandes d’E/S que le pilote envoie à la cible d’E/S (voir WdfRequestGetFileObject). Ce membre est facultatif et peut être NULL. Si la valeur de Type n’est pas WdfIoTargetOpenUseExistingDevice, ce membre est ignoré.

TargetDeviceName

Si la valeur de Type est WdfIoTargetOpenByName, il s’agit d’une structure UNICODE_STRING qui contient le nom d’un appareil, d’un fichier ou d’une interface d’appareil. Pour plus d’informations sur le format de ce nom, consultez Noms d’objets.

Si la valeur de Type n’est pas WdfIoTargetOpenByName, ce membre est ignoré.

DesiredAccess

Si la valeur de Type est WdfIoTargetOpenByName, il s’agit d’une valeur ACCESS_MASK .

Si la valeur de Type n’est pas WdfIoTargetOpenByName, ce membre est ignoré.

KMDF Les valeurs possibles incluent les valeurs FILE_Xxxx_ACCESS telles que FILE_ANY_ACCESS, FILE_SPECIAL_ACCESS, FILE_READ_ACCESS ou FILE_WRITE_ACCESS, ainsi que GENERIC_READ, GENERIC_WRITE et GENERIC_ALL.

UMDF Les valeurs les plus couramment utilisées sont GENERIC_READ, GENERIC_WRITE ou les deux (GENERIC_READ | GENERIC_WRITE). Notez que ACCESS_MASK est une valeur DWORD. Pour plus d’informations sur ce membre, consultez le paramètre dwDesiredAccess de CreateFile dans le Kit de développement logiciel (SDK) Windows.

ShareAccess

Si la valeur de Type n’est pas WdfIoTargetOpenByName, ce membre est ignoré.

KMDF Si la valeur de Type est WdfIoTargetOpenByName, il s’agit d’un or au niveau du bit des indicateurs suivants (qui sont définis dans Wdm.h) ou de zéro.

Indicateur ShareAccess	Signification
FILE_SHARE_READ	Le pilote ne nécessite pas d’accès en lecture exclusif à l’appareil.
FILE_SHARE_WRITE	Le pilote ne nécessite pas d’accès exclusif en écriture à l’appareil.
FILE_SHARE_DELETE	Le pilote ne nécessite pas d’accès de suppression exclusif à l’appareil.

UMDF Pour plus d’informations sur ce membre, consultez le paramètre dwShareMode de la fonction CreateFile dans le Kit de développement logiciel (SDK) Windows.

La valeur zéro dans ShareAccess indique que le pilote nécessite un accès exclusif à l’appareil.

FileAttributes

KMDF Si la valeur de Type est WdfIoTargetOpenByName, il s’agit d’un or au niveau du bit des indicateurs FILE_ATTRIBUTE_Xxxx définis dans Wdm.h. La plupart des pilotes spécifient FILE_ATTRIBUTE_NORMAL. Pour plus d’informations sur ces indicateurs, consultez ZwCreateFile.

UMDF Pour plus d’informations sur ce membre, consultez le paramètre dwFlagsAndAttributes de la fonction CreateFile dans le Kit de développement logiciel (SDK) Windows.

Si la valeur de Type n’est pas WdfIoTargetOpenByName, ce membre est ignoré.

CreateDisposition

KMDF Si la valeur de Type est WdfIoTargetOpenByName, cette valeur indique une action que le système doit effectuer lors de l’ouverture d’un fichier. Pour obtenir la liste des valeurs possibles, consultez ZwCreateFile.

UMDF Pour plus d’informations sur ce membre, consultez le paramètre dwCreationDisposition de la fonction CreateFile dans le Kit de développement logiciel (SDK) Windows.

Si la valeur de Type n’est pas WdfIoTargetOpenByName, ce membre est ignoré.

CreateOptions

Ce membre n’est pas applicable aux pilotes UMDF.

KMDF Si la valeur de Type est WdfIoTargetOpenByName, il s’agit d’un or au niveau du bit des indicateurs d’option de fichier. Pour obtenir la liste des indicateurs possibles, consultez ZwCreateFile. Si la valeur de Type n’est pas WdfIoTargetOpenByName, ce membre est ignoré.

EaBuffer

Ce membre n’est pas applicable aux pilotes UMDF.

KMDF Si la valeur de Type est WdfIoTargetOpenByName, ce membre pointe vers une mémoire tampon d’attributs étendus. En règle générale, les pilotes fournissent null pour cette valeur. Si la valeur de Type n’est pas WdfIoTargetOpenByName, ce membre est ignoré.

EaBufferLength

Ce membre n’est pas applicable aux pilotes UMDF.

KMDF Si la valeur de Type est WdfIoTargetOpenByName, il s’agit de la longueur de la mémoire tampon des attributs étendus. En règle générale, les pilotes fournissent zéro pour cette valeur. Si la valeur de Type n’est pas WdfIoTargetOpenByName, ce membre est ignoré.

AllocationSize

Ce membre n’est pas applicable aux pilotes UMDF.

KMDF Si la valeur de Type est WdfIoTargetOpenByName, ce membre spécifie la taille, en octets, que le système doit allouer initialement pour le fichier, s’il crée un fichier. Cette valeur est facultative et peut être égale à zéro. Si la valeur de Type n’est pas WdfIoTargetOpenByName, ce membre est ignoré.

FileInformation

Ce membre n’est pas applicable aux pilotes UMDF.

KMDF Si la valeur de Type est WdfIoTargetOpenByName, ce membre reçoit status informations lorsque l’appel à WdfIoTargetOpen est retourné. Les informations sont l’une des valeurs suivantes : FILE_CREATED, FILE_OPENED, FILE_OVERWRITTEN, FILE_SUPERSEDED, FILE_EXISTS ou FILE_DOES_NOT_EXIST. Si la valeur de Type n’est pas WdfIoTargetOpenByName, ce membre est ignoré.

FileName

Ce membre n’est pas applicable aux pilotes KMDF.

UMDF Structure UNICODE_STRING qui contient le nom du fichier à partir duquel créer un objet file. Ce membre est facultatif et s’applique uniquement lorsque la valeur de Type est WdfIoTargetOpenLocalTargetByFile. La plupart des pilotes spécifient null ici, sauf si la cible inférieure prend en charge l’accès à l’espace de noms de périphérique. Si elle est fournie, la chaîne ne doit pas contenir de caractères séparateurs de chemin (barre oblique ou barre oblique inverse).

Remarques

Les pilotes doivent initialiser la structure WDF_IO_TARGET_OPEN_PARAMS en appelant l’une des fonctions suivantes :

WDF_IO_TARGET_OPEN_PARAMS_INIT_EXISTING_DEVICE, si votre pilote peut identifier un appareil cible en fournissant un pointeur vers une structure de DEVICE_OBJECT .
WDF_IO_TARGET_OPEN_PARAMS_INIT_CREATE_BY_NAME, si la cible d’E/S est un appareil, un fichier ou une interface de périphérique, et si votre pilote peut fournir le nom de l’appareil, du fichier ou de l’interface de périphérique. Si vous spécifiez le nom d’un fichier qui existe déjà, le système remplace le fichier existant. Si le fichier n’existe pas, le système le crée.
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME, si la cible d’E/S est un appareil, un fichier ou une interface de périphérique, et si votre pilote peut fournir le nom de l’appareil, du fichier ou de l’interface de périphérique. Si vous spécifiez le nom d’un fichier qui existe déjà, le système ouvre le fichier existant. Si le fichier n’existe pas, l’opération d’ouverture échoue.
WDF_IO_TARGET_OPEN_PARAMS_INIT_REOPEN, si la fonction de rappel EvtIoTargetRemoveCanceled de votre pilote rouvre une cible d’E/S distante, car l’appareil n’a pas été supprimé.
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, si votre pilote UMDF doit envoyer des requêtes créées par le pilote à des cibles inférieures qui nécessitent un objet de fichier associé.