Funzione IoGetDeviceProperty (wdm.h)
La routine IoGetDeviceProperty recupera informazioni su un dispositivo, ad esempio informazioni di configurazione e il nome del relativo PDO.
Sintassi
NTSTATUS IoGetDeviceProperty(
[in] PDEVICE_OBJECT DeviceObject,
[in] DEVICE_REGISTRY_PROPERTY DeviceProperty,
[in] ULONG BufferLength,
[out, optional] PVOID PropertyBuffer,
[out] PULONG ResultLength
);
Parametri
[in] DeviceObject
Puntatore all'oggetto dispositivo fisico (PDO) per il dispositivo sottoposto a query.
[in] DeviceProperty
Enumeratore DEVICE_REGISTRY_PROPERTYtipizzato che identifica la proprietà del dispositivo da recuperare.
[in] BufferLength
Specifica le dimensioni, in byte, del chiamante fornito PropertyBuffer.
[out, optional] PropertyBuffer
Puntatore a un buffer fornito dal chiamante per ricevere le informazioni sulla proprietà. Il buffer può essere allocato dalla memoria di paging. Il tipo di buffer è determinato dal DeviceProperty (vedere sopra).
[out] ResultLength
Puntatore a ULONG per ricevere le dimensioni delle informazioni sulla proprietà restituite in PropertyBuffer. Se IoGetDeviceProperty restituisce STATUS_BUFFER_TOO_SMALL, imposta questo parametro sulla lunghezza del buffer richiesta.
Valore restituito
IoGetDeviceProperty restituisce STATUS_SUCCESS se la chiamata ha avuto esito positivo. I valori restituiti di errore possibili includono quanto segue.
| Codice restituito | Descrizione |
|---|---|
| STATUS_BUFFER_TOO_SMALL | Il buffer in corrispondenza del PropertyBuffer era troppo piccolo. resultLength punta alla lunghezza del buffer richiesta. |
| STATUS_INVALID_PARAMETER_2 | Il DeviceProperty specificato non è una delle proprietà gestite da questa routine. |
| STATUS_INVALID_DEVICE_REQUEST | Possibilmente indica che il DeviceObject specificato non era un puntatore PDO valido. |
Osservazioni
IoGetDeviceProperty recupera le informazioni di configurazione del dispositivo dal Registro di sistema. Utilizzare questa routine, anziché accedere direttamente al Registro di sistema, per isolare un driver dalle differenze tra le piattaforme e dalle possibili modifiche nella struttura del Registro di sistema.
Per molte richieste di DeviceProperty, possono essere necessarie due o più chiamate a IoGetDeviceProperty per determinare l'BufferLength necessario. La prima chiamata deve usare un valore di tipo best-guess. Se lo stato restituito è STATUS_BUFFER_TOO_SMALL, il driver deve liberare il buffer corrente, allocare un buffer delle dimensioni restituite in ResultLengthe chiamare di nuovo IoGetDeviceProperty. Poiché alcune delle proprietà di installazione sono dinamiche, le dimensioni dei dati possono cambiare tra il momento in cui vengono restituite le dimensioni necessarie e il driver chiama nuovamente questa routine. Pertanto, i driver devono chiamare IoGetDeviceProperty all'interno di un ciclo che viene eseguito fino a quando lo stato restituito non è STATUS_BUFFER_TOO_SMALL.
I driver di funzione che supportano i dispositivi in un bus legacy e un bus PnP possono usare il DevicePropertyBusNumber, DevicePropertyBusTypeGuide proprietà DevicePropertyLegacyBusType per distinguere tra gli autobus.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Disponibile a partire da Windows 2000. |
| piattaforma di destinazione | Universale |
| intestazione | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| libreria | NtosKrnl.lib |
| dll | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| regole di conformità DDI | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |