DEVICE_OBJECT structure (wdm.h)
La structure DEVICE_OBJECT est utilisée par le système d’exploitation pour représenter un objet d’appareil. Un objet d’appareil représente un appareil logique, virtuel ou physique pour lequel un pilote gère les demandes d’E/S.
Syntaxe
typedef struct _DEVICE_OBJECT {
CSHORT Type;
USHORT Size;
LONG ReferenceCount;
struct _DRIVER_OBJECT *DriverObject;
struct _DEVICE_OBJECT *NextDevice;
struct _DEVICE_OBJECT *AttachedDevice;
struct _IRP *CurrentIrp;
PIO_TIMER Timer;
ULONG Flags;
ULONG Characteristics;
__volatile PVPB Vpb;
PVOID DeviceExtension;
DEVICE_TYPE DeviceType;
CCHAR StackSize;
union {
LIST_ENTRY ListEntry;
WAIT_CONTEXT_BLOCK Wcb;
} Queue;
ULONG AlignmentRequirement;
KDEVICE_QUEUE DeviceQueue;
KDPC Dpc;
ULONG ActiveThreadCount;
PSECURITY_DESCRIPTOR SecurityDescriptor;
KEVENT DeviceLock;
USHORT SectorSize;
USHORT Spare1;
struct _DEVOBJ_EXTENSION *DeviceObjectExtension;
PVOID Reserved;
} DEVICE_OBJECT, *PDEVICE_OBJECT;
Membres
Type
Utilisé par le système d’exploitation pour indiquer qu’un objet est un objet d’appareil. Pour les objets d’appareil, la valeur de ce membre est 3. Il s’agit d’un membre en lecture seule.
Size
Spécifie la taille, en octets, de l’objet d’appareil. Cette taille inclut l’extension de périphérique spécifiée par le pilote pointée par le membre DeviceExtension , mais n’inclut pas l’extension d’objet de périphérique opaque pointée par le membre DeviceObjectExtension . Size est un membre en lecture seule.
ReferenceCount
Utilisé par le gestionnaire d’E/S pour suivre le nombre de handles ouverts pour l’appareil qui sont associés à l’objet d’appareil. Cela permet au gestionnaire d’E/S d’éviter de décharger un pilote lorsqu’il existe des poignées en attente pour le ou les périphériques du pilote. Il s’agit d’un membre en lecture seule.
DriverObject
Pointeur vers l’objet driver (DRIVER_OBJECT), qui représente l’image chargée du pilote qui a été entrée dans les routines DriverEntry et AddDevice . Ce membre est défini par le gestionnaire d’E/S lors d’un appel réussi à IoCreateDevice ou IoCreateDeviceSecure. Il s’agit d’un membre en lecture seule.
NextDevice
Pointeur vers l’objet de périphérique suivant, le cas échéant, qui a été créé par le même pilote. Le gestionnaire d’E/S met à jour cette liste à chaque appel réussi à IoCreateDevice ou IoCreateDeviceSecure.
Un pilote non-Plug-and-Play (PnP) en cours de déchargement doit parcourir (« parcourir ») la liste de ses objets d’appareil et les supprimer. Un pilote PnP n’a pas besoin d’parcourir cette liste d’objets d’appareil. Au lieu de cela, les pilotes PnP effectuent leur nettoyage pendant l’opération PnP de suppression de périphérique (IRP_MN_REMOVE_DEVICE).
Un pilote qui recrée dynamiquement ses objets d’appareil utilise également ce membre. Il s’agit d’un membre en lecture/écriture.
AttachedDevice
Pointeur vers l’objet d’appareil attaché. S’il n’y a pas d’objet d’appareil attaché, ce membre est NULL. L’objet d’appareil vers lequel pointe le membre AttachedDevice est généralement l’objet d’appareil d’un pilote de filtre, qui intercepte les demandes d’E/S initialement ciblées sur l’appareil représenté par l’objet de périphérique. Pour plus d’informations, consultez les rubriques IoAttachDevice et IoAttachDeviceByPointer . Il s’agit d’un membre opaque.
CurrentIrp
Pointeur vers l’IRP actuel si le pilote a une routine StartIo dont le point d’entrée a été défini dans l’objet pilote et si le pilote traite actuellement les IRP. Sinon, ce membre est NULL. Pour plus d’informations, consultez les rubriques IoStartPacket et IoStartNextPacket . Il s’agit d’un membre en lecture seule.
Timer
Pointeur vers un objet minuteur. Cela permet au gestionnaire d’E/S d’appeler une routine de minuteur fournie par le pilote toutes les secondes. Pour plus d’informations, consultez IoInitializeTimer. Il s’agit d’un membre en lecture/écriture.
Flags
Les pilotes de périphérique effectuent une opération OR au niveau du bit avec ce membre dans leurs nouveaux objets d’appareil en utilisant une ou plusieurs des valeurs définies par le système suivantes.
Pour plus d’informations sur la définition du membre Flags , consultez Initialisation d’un objet Device.
| Valeur | Signification |
|---|---|
| DO_VERIFY_VOLUME (0x00000002) | Les pilotes de média amovible définissent cet indicateur pendant qu’ils traitent les demandes de transfert. Ces pilotes doivent également case activée pour cet indicateur dans la cible pour une demande de transfert avant de transférer des données. Pour plus d’informations, consultez la rubrique Prise en charge du support amovible . |
| DO_BUFFERED_IO (0x00000004) | Spécifie le type de mise en mémoire tampon utilisée par le gestionnaire d’E/S pour les demandes d’E/S envoyées à la pile d’appareils. Pilotes de niveau supérieur OU ce membre avec la même valeur que le pilote inférieur suivant dans la pile, sauf éventuellement pour les pilotes de niveau supérieur. |
| DO_EXCLUSIVE (0x00000008) | Indique que le pilote met en service un appareil exclusif, tel qu’un périphérique vidéo, série, parallèle ou audio. Les pilotes WDM ne doivent pas définir cet indicateur. Pour plus d’informations, consultez la rubrique Spécification de l’accès exclusif aux objets d’appareil . |
| DO_DIRECT_IO (0x00000010) | Voir DO_BUFFERED_IO. |
| DO_MAP_IO_BUFFER (0x00000020) | Cet indicateur n’est plus utilisé. Les pilotes ne doivent pas définir cet indicateur. |
| DO_DEVICE_INITIALIZING (0x00000080) | Le gestionnaire d’E/S définit cet indicateur lorsqu’il crée l’objet d’appareil. Un pilote de fonction de périphérique ou un pilote de filtre efface l’indicateur dans sa routine AddDevice , après : (1) Attache l’objet de périphérique à la pile de périphériques. (2) Établit l’état d’alimentation de l’appareil. (3) Effectue une opération OR au niveau du bit sur le membre avec l’un des indicateurs d’alimentation (si nécessaire). Le gestionnaire Plug-and-Play (PnP) vérifie que l’indicateur est clair après le retour de la routine AddDevice. |
| DO_SHUTDOWN_REGISTERED (0x00000800) | Utilisé par le gestionnaire d’E/S pour indiquer qu’un pilote a inscrit l’objet de périphérique pour les notifications d’arrêt. Cet indicateur ne doit pas être utilisé par les pilotes. |
| DO_BUS_ENUMERATED_DEVICE (0x00001000) | Le système d’exploitation définit cet indicateur dans chaque objet d’appareil physique (PDO). Les pilotes ne doivent pas modifier cet indicateur. |
| DO_POWER_PAGABLE (0x00002000) | Les pilotes paginables compatibles avec Microsoft Windows 2000 et versions ultérieures de Windows, ne font pas partie du chemin d’accès de pagination et ne nécessitent pas d’appel actuel doivent définir cet indicateur. Le système appelle ces pilotes à IRQL = PASSIVE_LEVEL. Les pilotes ne peuvent pas définir cet indicateur et ce DO_POWER_INRUSH. Tous les pilotes pour WDM, Microsoft Windows 98 et Windows Millennium Edition doivent définir DO_POWER_PAGABLE. |
| DO_POWER_INRUSH (0x00004000) | Les pilotes des appareils qui nécessitent un courant d’appel lorsque l’appareil est allumé doivent définir cet indicateur. Un pilote ne peut pas définir cet indicateur et ce DO_POWER_PAGABLE. |
| DO_DEVICE_TO_BE_RESET (0x04000000) | Le gestionnaire d’E/S définit cet indicateur en tant que signal pour que le pilote de bus réinitialise l’appareil. Les autres pilotes ne doivent pas utiliser cet indicateur. |
| DO_DAX_VOLUME (0x10000000) | Indique qu’un volume est un volume DAX. |
Characteristics
Spécifie une ou plusieurs constantes définies par le système, combinées à une opération OR au niveau du bit, qui fournissent des informations supplémentaires sur le périphérique du pilote. Ces constantes sont les suivantes :
| Valeur | Signification |
|---|---|
| FILE_AUTOGENERATED_DEVICE_NAME | Indique au gestionnaire d’E/S de générer un nom pour l’appareil, au lieu que l’appelant spécifie un DeviceName lorsqu’il appelle cette routine. Le gestionnaire d’E/S vérifie que le nom est unique. Cette caractéristique est généralement spécifiée par un pilote de bus PnP pour générer un nom pour un objet de périphérique physique (PDO) pour un appareil enfant sur le même bus. |
| FILE_CHARACTERISTIC_PNP_DEVICE | Indique que l’objet d’appareil fait partie d’une pile de Plug-and-Play (PnP). Cette caractéristique est requise si un pilote de bus (ou un pilote de filtre de bus) inscrit la prise en charge de WMI pour un objet de périphérique qui n’a pas encore reçu la demande de IRP_MN_START_DEVICE . FILE_CHARACTERISTIC_PNP_DEVICE est également nécessaire si un pilote de fonction ou de filtre s’inscrit pour WMI avant de l’attacher à sa pile de périphériques. |
| FILE_CHARACTERISTIC_TS_DEVICE | Indique que l’objet d’appareil fait partie d’une pile d’appareils Terminal Services. Les pilotes ne doivent pas définir cette caractéristique. |
| FILE_CHARACTERISTIC_WEBDAV_DEVICE | Indique qu’un système de fichiers Web-based Distributed Authoring and Versioning (WebDAV) est monté sur l’appareil. Les pilotes ne doivent pas définir cette caractéristique. |
| FILE_DEVICE_IS_MOUNTED | Indique qu’un système de fichiers est monté sur l’appareil. Les pilotes ne doivent pas définir cette caractéristique. |
| FILE_DEVICE_SECURE_OPEN | Indique au gestionnaire d’E/S d’appliquer le descripteur de sécurité de l’objet d’appareil aux ouvertures relatives et au nom de fichier de fin s’ouvre pour l’appareil. Pour plus d’informations, consultez la rubrique Contrôle de l’accès à l’espace de noms des appareils . |
| FILE_FLOPPY_DISKETTE | Indique que l’appareil est une unité de disquette. |
| FILE_READ_ONLY_DEVICE | Indique que l’appareil ne peut pas être écrit dans. |
| FILE_REMOTE_DEVICE | Indique que l’appareil est distant. |
| FILE_REMOVABLE_MEDIA | Indique que le périphérique de stockage prend en charge le support amovible. Notez que cette caractéristique indique un média amovible, et non un appareil amovible. Par exemple, les pilotes des périphériques de lecteur JAZ doivent spécifier cette caractéristique, mais pas les pilotes pour les disques flash PCMCIA. |
| FILE_VIRTUAL_VOLUME | Indique que le volume est virtuel. Les pilotes ne doivent pas définir cette caractéristique. |
| FILE_WRITE_ONCE_MEDIA | Indique que l’appareil prend en charge le média en écriture unique. Les pilotes ne définissent pas ce membre directement. Pour plus d’informations sur la définition des caractéristiques de l’appareil, consultez la rubrique Spécification des caractéristiques de l’appareil . |
| FILE_CHARACTERISTIC_CSV | Indique que l’appareil est un volume partagé de cluster (CSV). |
| FILE_DEVICE_ALLOW_APPCONTAINER_TRAVERSAL | Le gestionnaire d’E/S effectue normalement une case activée de sécurité complète pour l’accès via chaque fichier ouvert lorsque le client est un conteneur d’application. Le paramètre de cet indicateur contourne ce case activée d’accès de traverse appliqué si le jeton client dispose déjà de privilèges de traversée. |
| FILE_PORTABLE_DEVICE | Indique que la pile sous-jacente considère l’appareil comme portable. Cela est utilisé par la pile de stockage et signifie que l’appareil ne se trouve pas dans le conteneur de l’ordinateur local et n’est pas sur un type de bus fixe. |
Vpb
Pointeur vers le bloc de paramètres de volume (VPB) associé à l’objet d’appareil. Pour les pilotes de système de fichiers, le VPB peut fournir une connexion à n’importe quel objet de périphérique logique sans nom qui représente une instance d’un volume monté. Il s’agit d’un membre opaque.
DeviceExtension
Pointeur vers l’extension d’appareil. La structure et le contenu de l’extension de périphérique sont définis par le pilote. La taille est déterminée par le pilote, spécifiée dans l’appel du pilote à IoCreateDevice ou IoCreateDeviceSecure. Pour plus d’informations sur les extensions d’appareil, consultez Extensions d’appareil. Il s’agit d’un membre en lecture seule. Toutefois, l’objet vers lequel le membre pointe peut être modifié par le pilote.
DeviceType
Défini par IoCreateDevice et IoCreateDeviceSecure à l’aide de la valeur spécifiée pour le paramètre DeviceType de cette routine. Pour plus d’informations, consultez la rubrique Spécification des types d’appareils .
StackSize
Spécifie le nombre minimal d’emplacements de pile dans les irps à envoyer à ce pilote. IoCreateDevice et IoCreateDeviceSecure définissent ce membre sur 1 dans les objets d’appareil nouvellement créés ; les pilotes de niveau inférieur peuvent donc ignorer ce membre. Le gestionnaire d’E/S définit automatiquement le membre StackSize dans l’objet d’appareil d’un pilote de niveau supérieur sur la valeur appropriée si le pilote appelle IoAttachDevice ou IoAttachDeviceToDeviceStack. Seul un pilote de niveau supérieur qui se chaîne sur un autre pilote avec IoGetDeviceObjectPointer doit définir explicitement la valeur de StackSize dans ses propres objets d’appareil sur 1 + la valeur StackSize de l’objet de périphérique du pilote inférieur suivant.
Queue
Utilisé en interne par le gestionnaire d’E/S pour mettre en file d’attente l’objet d’appareil lorsque cela est nécessaire. Il s’agit d’un membre opaque.
Queue.ListEntry
Structure LIST_ENTRY qui contient des pointeurs vers l’avant et vers l’arrière pour une liste doublement liée.
Queue.Wcb
Informations sur le contexte de l’appareil utilisées par le gestionnaire d’E/S.
AlignmentRequirement
Spécifie l’exigence d’alignement d’adresse de l’appareil pour les transferts de données. La valeur doit être l’une des valeurs FILE_XXX_ALIGNMENT définies dans Wdm.h. Pour plus d’informations, consultez les rubriques Initialisation d’un objet d’appareil, GetDmaAlignment et ZwQueryInformationFile .
DeviceQueue
Objet de file d’attente d’appareil pour l’objet d’appareil. L’objet de file d’attente de périphérique contient tous les IRP qui attendent d’être traités par le pilote associé à l’objet de périphérique. Pour plus d’informations, consultez la rubrique Files d’attente IRP gérées par le pilote . Il s’agit d’un membre opaque.
Dpc
Objet d’appel de procédure différée (DPC) pour l’objet d’appareil. Pour plus d’informations, consultez la rubrique Présentation des objets DPC . Il s’agit d’un membre opaque.
ActiveThreadCount
Réservé pour un usage futur. Il s’agit d’un membre opaque.
SecurityDescriptor
Spécifie un descripteur de sécurité (SECURITY_DESCRIPTOR) pour l’objet d’appareil lors de sa création. Si ce membre a la valeur NULL, l’objet d’appareil reçoit les paramètres de sécurité par défaut. Il s’agit d’un membre en lecture seule, bien que le membre puisse être modifié via la fonction ZwSetSecurityObject .
DeviceLock
Objet d’événement de synchronisation alloué par le gestionnaire d’E/S. Le gestionnaire d’E/S obtient son objet d’événement avant de distribuer une demande de montage ou de montage-vérification à un pilote de système de fichiers. Il s’agit d’un membre opaque.
SectorSize
Si l’objet d’appareil ne représente pas de volume, ce membre est défini sur zéro. Si l’objet d’appareil représente un volume, ce membre spécifie la taille de secteur du volume, en octets. Le gestionnaire d’E/S utilise ce membre pour s’assurer que toutes les opérations de lecture, d’écriture et de définition de la position de fichier émises sont alignées correctement lorsque la mise en mémoire tampon intermédiaire est désactivée. Une valeur d’octets système par secteur par défaut est utilisée lors de la création de l’objet d’appareil, mais des pilotes de système de fichiers ; et plus rarement, les pilotes hérités et minifiltres, peuvent mettre à jour cette valeur basée sur la géométrie du matériel de volume sous-jacent lors d’un montage. Les autres pilotes ne doivent pas modifier ce membre.
Spare1
Réservé pour le système. Il s’agit d’un membre opaque.
DeviceObjectExtension
Pointeur vers une extension d’objet d’appareil utilisée par le gestionnaire d’E/S et le gestionnaire PnP pour stocker des informations sur l’état de l’appareil. Il s’agit d’un membre opaque.
Reserved
Réservé pour le système. Il s’agit d’un membre opaque.
Remarques
Le système d’exploitation représente les appareils par objets d’appareil. Pour plus d’informations, consultez la rubrique Device Objects and Device Stacks .
Les pilotes créent des objets d’appareil à l’aide des routines IoCreateDevice et IoCreateDeviceSecure . Pour plus d’informations sur la création d’objets d’appareil, consultez Création d’un objet d’appareil.
Un objet d’appareil est partiellement opaque. Les pilotes ne définissent pas directement les membres de l’objet de périphérique, sauf indication contraire. Pour plus d’informations sur les membres que les pilotes peuvent modifier directement, consultez Initialisation d’un objet device. Pour plus d’informations sur les autres propriétés d’objet d’appareil, consultez Propriétés des objets d’appareil.
Les membres opaques au sein d’un objet d’appareil doivent être considérés comme inaccessibles. Les pilotes qui ont des dépendances sur les emplacements des membres de l’objet ou l’accès à des membres opaques peuvent ne pas rester portables et interopérables avec d’autres pilotes au fil du temps.
Le pilote de port vidéo fourni par le système configure les champs des objets d’appareil qu’il crée pour le compte des pilotes de miniport vidéo.
Le pilote de port SCSI fourni par le système configure les champs des objets de périphérique qu’il crée pour le compte des pilotes miniport SCSI.
La bibliothèque NDIS fournie par le système configure les champs des objets d’appareil qu’elle crée pour le compte des pilotes miniport NDIS.
Configuration requise
| Condition requise | Valeur |
|---|---|
| En-tête | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h) |