DEVICE_OBJECT struttura (wdm.h)
La struttura DEVICE_OBJECT viene usata dal sistema operativo per rappresentare un oggetto dispositivo. Un oggetto dispositivo rappresenta un dispositivo logico, virtuale o fisico per cui un driver gestisce le richieste di I/O.
Sintassi
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;
Members
Type
Usato dal sistema operativo per indicare che un oggetto è un oggetto dispositivo. Per gli oggetti dispositivo, il valore di questo membro è 3. Si tratta di un membro di sola lettura.
Size
Specifica le dimensioni, in byte, dell'oggetto dispositivo. Questa dimensione include l'estensione del dispositivo specificata dal driver a cui punta il membro DeviceExtension , ma non include l'estensione dell'oggetto dispositivo opaco a cui punta il membro DeviceObjectExtension . Le dimensioni sono un membro di sola lettura.
ReferenceCount
Usato dalla gestione I/O per tenere traccia del numero di handle aperti per il dispositivo associato all'oggetto dispositivo. Ciò consente al gestore I/O di evitare di scaricare un driver quando sono presenti handle in sospeso per i dispositivi del driver. Si tratta di un membro di sola lettura.
DriverObject
Puntatore all'oggetto driver (DRIVER_OBJECT), che rappresenta l'immagine caricata del driver immesso nelle routine DriverEntry e AddDevice . Questo membro viene impostato dal gestore di I/O dopo una chiamata riuscita a IoCreateDevice o IoCreateDeviceSecure. Si tratta di un membro di sola lettura.
NextDevice
Puntatore all'oggetto dispositivo successivo, se presente, creato dallo stesso driver. La gestione I/O aggiorna questo elenco a ogni chiamata riuscita a IoCreateDevice o IoCreateDeviceSecure.
Un driver non Plug and Play (PnP) che viene scaricato deve attraversare ("walk") l'elenco degli oggetti del dispositivo ed eliminarli. Un driver PnP non deve seguire questo elenco di oggetti dispositivo. I driver PnP eseguono invece la pulizia durante l'operazione di rimozione del dispositivo PnP (IRP_MN_REMOVE_DEVICE).
Un driver che ricrea i relativi oggetti dispositivo in modo dinamico usa anche questo membro. Si tratta di un membro di lettura/scrittura.
AttachedDevice
Puntatore all'oggetto dispositivo collegato. Se non è presente alcun oggetto dispositivo collegato, questo membro è NULL. L'oggetto dispositivo a cui punta il membro AttachedDevice in genere è l'oggetto dispositivo di un driver di filtro, che intercetta le richieste di I/O originariamente destinate al dispositivo rappresentato dall'oggetto dispositivo. Per altre informazioni, vedere gli argomenti IoAttachDevice e IoAttachDeviceByPointer . Si tratta di un membro opaco.
CurrentIrp
Puntatore all'IRP corrente se il driver ha una routine StartIo il cui punto di ingresso è stato impostato nell'oggetto driver e se il driver sta attualmente elaborando IRP. In caso contrario, questo membro è NULL. Per altre informazioni, vedere gli argomenti IoStartPacket e IoStartNextPacket. Si tratta di un membro di sola lettura.
Timer
Puntatore a un oggetto timer. Ciò consente al gestore di I/O di chiamare una routine timer fornita dal driver ogni secondo. Per altre informazioni, vedere IoInitializeTimer. Si tratta di un membro di lettura/scrittura.
Flags
I driver di dispositivo eseguono un'operazione OR bit per bit con questo membro negli oggetti dispositivo appena creati usando uno o più dei valori definiti dal sistema seguenti.
Per altre informazioni su come impostare il membro Flags , vedere Inizializzazione di un oggetto Device.
| Valore | Significato |
|---|---|
| DO_VERIFY_VOLUME (0x00000002) | I driver multimediali rimovibili impostano questo flag durante l'elaborazione delle richieste di trasferimento. Tali driver devono anche verificare la presenza di questo flag nella destinazione per una richiesta di trasferimento prima di trasferire i dati. Per altre informazioni, vedere l'argomento Supporto supporti rimovibili . |
| DO_BUFFERED_IO (0x00000004) | Specifica il tipo di buffering usato dalla gestione I/O per le richieste di I/O inviate allo stack di dispositivi. Driver di livello superiore OR questo membro con lo stesso valore del driver inferiore successivo nello stack, tranne possibilmente per i driver di livello più alto. |
| DO_EXCLUSIVE (0x00000008) | Indica che il driver servizi un dispositivo esclusivo, ad esempio un video, seriale, parallelo o dispositivo audio. I driver WDM non devono impostare questo flag. Per altre informazioni, vedere l'argomento Specifica dell'accesso esclusivo agli oggetti dispositivo . |
| DO_DIRECT_IO (0x00000010) | Vedere DO_BUFFERED_IO. |
| DO_MAP_IO_BUFFER (0x00000020) | Questo flag non viene più usato. I driver non devono impostare questo flag. |
| DO_DEVICE_INITIALIZING (0x00000080) | Gestione I/O imposta questo flag quando crea l'oggetto dispositivo. Un driver di funzione dispositivo o un driver di filtro cancella il flag nella routine AddDevice , dopo di esso: (1) Collega l'oggetto dispositivo allo stack di dispositivi. (2) Stabilisce lo stato di alimentazione del dispositivo. (3) Esegue un'operazione OR bit per bit sul membro con uno dei flag di alimentazione (se necessario). Il gestore Plug and Play (PnP) verifica che il flag sia deselezionato dopo che la routine AddDevice restituisce. |
| DO_SHUTDOWN_REGISTERED (0x00000800) | Usato dal gestore di I/O per indicare che un driver ha registrato l'oggetto dispositivo per le notifiche di arresto. Questo flag non deve essere usato dai driver. |
| DO_BUS_ENUMERATED_DEVICE (0x00001000) | Il sistema operativo imposta questo flag in ogni oggetto dispositivo fisico (PDO). I driver non devono modificare questo flag. |
| DO_POWER_PAGABLE (0x00002000) | I driver impaginabili compatibili con Microsoft Windows 2000 e versioni successive di Windows, non fanno parte del percorso di paging e non richiedono inrush corrente deve impostare questo flag. Il sistema chiama tali driver in IRQL = PASSIVE_LEVEL. I driver non possono impostare sia questo flag che DO_POWER_INRUSH. Tutti i driver per WDM, Microsoft Windows 98 e Windows Millennium Edition devono impostare DO_POWER_PAGABLE. |
| DO_POWER_INRUSH (0x00004000) | I driver di dispositivi che richiedono inrush corrente quando il dispositivo è attivato deve impostare questo flag. Un driver non può impostare sia questo flag che DO_POWER_PAGABLE. |
| DO_DEVICE_TO_BE_RESET (0x04000000) | Il gestore I/O imposta questo flag come segnale per il driver del bus per reimpostare il dispositivo. Altri driver non devono usare questo flag. |
| DO_DAX_VOLUME (0x10000000) | Indica che un volume è un volume DAX. |
Characteristics
Specifica una o più costanti definite dal sistema, combinate con un'operazione OR bit per bit, che forniscono informazioni aggiuntive sul dispositivo del driver. Queste costanti includono quanto segue:
| Valore | Significato |
|---|---|
| FILE_AUTOGENERATED_DEVICE_NAME | Indirizza la gestione I/O per generare un nome per il dispositivo, anziché il chiamante che specifica un Nome dispositivo quando chiama questa routine. Il gestore di I/O assicura che il nome sia univoco. Questa caratteristica è in genere specificata da un driver del bus PnP per generare un nome per un oggetto dispositivo fisico (PDO) per un dispositivo figlio nello stesso bus. |
| FILE_CHARACTERISTIC_PNP_DEVICE | Indica che l'oggetto dispositivo fa parte di uno stack di Plug and Play (PnP). Questa caratteristica è necessaria se un driver del bus (o un driver di filtro del bus) registra il supporto WMI per un oggetto dispositivo che non ha ancora ricevuto la richiesta di IRP_MN_START_DEVICE . FILE_CHARACTERISTIC_PNP_DEVICE è necessario anche se una funzione o un driver di filtro registra per WMI prima di collegarsi allo stack di dispositivi. |
| FILE_CHARACTERISTIC_TS_DEVICE | Indica che l'oggetto dispositivo fa parte di uno stack di dispositivi Servizi terminal. I driver non devono impostare questa caratteristica. |
| FILE_CHARACTERISTIC_WEBDAV_DEVICE | Indica che un file system Di creazione distribuita e controllo delle versioni (WebDAV) basato sul Web viene montato nel dispositivo. I driver non devono impostare questa caratteristica. |
| FILE_DEVICE_IS_MOUNTED | Indica che un file system è montato nel dispositivo. I driver non devono impostare questa caratteristica. |
| FILE_DEVICE_SECURE_OPEN | Indica al gestore di I/O di applicare il descrittore di sicurezza dell'oggetto dispositivo all'apertura relativa e all'apertura del nome del file finale per il dispositivo. Per altre informazioni, vedere l'argomento Controllo dell'accesso allo spazio dei nomi dei dispositivi . |
| FILE_FLOPPY_DISKETTE | Indica che il dispositivo è un dispositivo disco floppy. |
| FILE_READ_ONLY_DEVICE | Indica che il dispositivo non può essere scritto. |
| FILE_REMOTE_DEVICE | Indica che il dispositivo è remoto. |
| FILE_REMOVABLE_MEDIA | Indica che il dispositivo di archiviazione supporta supporti rimovibili. Si noti che questa caratteristica indica supporti rimovibili, non un dispositivo rimovibile. Ad esempio, i driver per i dispositivi di unità JAZ devono specificare questa caratteristica, ma i driver per i dischi flash PCMCIA non devono. |
| FILE_VIRTUAL_VOLUME | Indica che il volume è virtuale. I driver non devono impostare questa caratteristica. |
| FILE_WRITE_ONCE_MEDIA | Indica che il dispositivo supporta supporti write-once. I driver non impostano direttamente questo membro. Per altre informazioni su come impostare le caratteristiche del dispositivo, vedere l'argomento Specifica delle caratteristiche del dispositivo . |
| FILE_CHARACTERISTIC_CSV | Indica che il dispositivo è un volume condiviso cluster (CSV). |
| FILE_DEVICE_ALLOW_APPCONTAINER_TRAVERSAL | IO Manager esegue in genere un controllo di sicurezza completo per l'attraversamento dell'accesso in ogni file aperto quando il client è un contenitore di app. L'impostazione di questo flag ignora questo attraversamento imposto verifica se il token client dispone già di privilegi di attraversamento. |
| FILE_PORTABLE_DEVICE | Indica che lo stack sottostante considera il dispositivo portatile. Viene usato dallo stack di archiviazione e significa che il dispositivo non si trova nel contenitore del computer locale e non si trova in un tipo di bus fisso. |
Vpb
Puntatore al blocco di parametri del volume (VPB) associato all'oggetto dispositivo. Per i driver del file system, il VPB può fornire una connessione a qualsiasi oggetto dispositivo logico senza nome che rappresenta un'istanza di un volume montato. Si tratta di un membro opaco.
DeviceExtension
Puntatore all'estensione del dispositivo. La struttura e il contenuto dell'estensione del dispositivo sono definiti dal driver. Le dimensioni sono determinate dal driver, specificate nella chiamata del driver a IoCreateDevice o IoCreateDeviceSecure. Per altre informazioni sulle estensioni del dispositivo, vedere Estensioni del dispositivo. Membro di sola lettura. Tuttavia, l'oggetto a cui punta il membro può essere modificato dal driver.
DeviceType
Impostato da IoCreateDevice e IoCreateDeviceSecure usando il valore specificato per il parametro DeviceType di tale routine. Per altre informazioni, vedere l'argomento Specifica dei tipi di dispositivo .
StackSize
Specifica il numero minimo di percorsi dello stack nei provider di integrazione da inviare a questo driver. IoCreateDevice e IoCreateDeviceSecure impostano questo membro su 1 negli oggetti dispositivo appena creati; i driver di livello più basso possono quindi ignorare questo membro. Il gestore di I/O imposta automaticamente il membro StackSize in un oggetto dispositivo del driver di livello superiore sul valore appropriato se il driver chiama IoAttachDevice o IoAttachDeviceToDeviceToDeviceStack. Solo un driver di livello superiore che si concatena su un altro driver con IoGetDeviceObjectPointer deve impostare in modo esplicito il valore di StackSize nei propri oggetti dispositivo su 1 + il valore StackSize dell'oggetto dispositivo del driver inferiore successivo.
Queue
Usato internamente dal gestore di I/O per accodare l'oggetto dispositivo quando è necessario. Si tratta di un membro opaco.
Queue.ListEntry
Struttura LIST_ENTRY che contiene puntatori avanti e indietro per un elenco collegato doubly.
Queue.Wcb
Informazioni sul contesto di dispositivo usate dal gestore di I/O.
AlignmentRequirement
Specifica il requisito di allineamento degli indirizzi del dispositivo per i trasferimenti di dati. Il valore deve essere uno dei valori FILE_XXX_ALIGNMENT definiti in Wdm.h. Per altre informazioni, vedere gli argomenti Inizializzazione di un oggetto Device, GetDmaAlignment e ZwQueryInformationFile .
DeviceQueue
Oggetto coda del dispositivo per l'oggetto dispositivo. L'oggetto coda del dispositivo contiene tutti i provider di integrazione in attesa di essere elaborati dal driver associato all'oggetto dispositivo. Per altre informazioni, vedere l'argomento Code IRP gestite dal driver . Si tratta di un membro opaco.
Dpc
Oggetto DPC (Deferred Procedure Call) per l'oggetto dispositivo. Per altre informazioni, vedere l'argomento Introduzione agli oggetti DPC . Si tratta di un membro opaco.
ActiveThreadCount
Riservato per utilizzi futuri. Si tratta di un membro opaco.
SecurityDescriptor
Specifica un descrittore di sicurezza (SECURITY_DESCRIPTOR) per l'oggetto dispositivo quando viene creato l'oggetto dispositivo. Se questo membro è NULL, l'oggetto dispositivo riceve le impostazioni di sicurezza predefinite. Si tratta di un membro di sola lettura, anche se il membro può essere modificato tramite la funzione ZwSetSecurityObject .
DeviceLock
Oggetto evento di sincronizzazione allocato dal gestore di I/O. Il gestore di I/O ottiene l'oggetto evento prima di inviare una richiesta di montaggio o di verifica del montaggio a un driver del file system. Si tratta di un membro opaco.
SectorSize
Se l'oggetto dispositivo non rappresenta un volume, questo membro viene impostato su zero. Se l'oggetto dispositivo rappresenta un volume, questo membro specifica le dimensioni del settore del volume, in byte. Il gestore di I/O usa questo membro per assicurarsi che tutte le operazioni di lettura, le operazioni di scrittura e le operazioni di posizione dei file rilasciate siano allineate correttamente quando il buffer intermedio è disabilitato. Quando l'oggetto dispositivo viene creato, viene utilizzato un valore byte di sistema predefinito per settore, ma i driver del file system; e più raramente, i driver legacy e minifilter possono aggiornare questo valore basato sulla geometria dell'hardware del volume sottostante quando si verifica un montaggio. Gli altri driver non devono modificare questo membro.
Spare1
Riservato per l'utilizzo nel sistema. Si tratta di un membro opaco.
DeviceObjectExtension
Puntatore a un'estensione dell'oggetto dispositivo usata dal gestore di I/O e dal gestore PnP per archiviare informazioni sullo stato del dispositivo. Si tratta di un membro opaco.
Reserved
Riservato per l'utilizzo nel sistema. Si tratta di un membro opaco.
Commenti
Il sistema operativo rappresenta i dispositivi in base agli oggetti dispositivo. Per altre informazioni, vedere l'argomento Oggetti dispositivo e Stack di dispositivi .
I driver creano oggetti dispositivo usando le routine IoCreateDevice e IoCreateDeviceSecure . Per altre informazioni su come creare oggetti dispositivo, vedere Creazione di un oggetto Device.
Un oggetto dispositivo è parzialmente opaco. I driver non impostano direttamente i membri dell'oggetto dispositivo, se non diversamente documentato. Per altre informazioni sui membri che i driver possono modificare direttamente, vedere Inizializzazione di un oggetto Device. Per informazioni su altre proprietà dell'oggetto dispositivo, vedere Proprietà degli oggetti dispositivo.
I membri opachi all'interno di un oggetto dispositivo devono essere considerati inaccessibili. I driver con dipendenze dalle posizioni dei membri degli oggetti o l'accesso a membri opachi potrebbero non rimanere portabili e interoperabili con altri driver nel tempo.
Il driver della porta video fornita dal sistema configura i campi degli oggetti dispositivo creati per conto dei driver video miniport.
Il driver di porta SCSI fornito dal sistema configura i campi degli oggetti dispositivo creati per conto dei driver miniport SCSI.
La libreria NDIS fornita dal sistema configura i campi degli oggetti dispositivo creati per conto dei driver miniport NDIS.
Requisiti
| Requisito | Valore |
|---|---|
| Intestazione | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h) |