Funzione IoGetDeviceProperty (wdm.h)
La routine IoGetDeviceProperty recupera informazioni su un dispositivo, ad esempio informazioni di configurazione e il nome del proprio 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
Specifica la proprietà del dispositivo richiesta. Deve essere uno dei valori di enumerazione seguenti DEVICE_REGISTRY_PROPERTY :
DevicePropertyAddress
Richiede l'indirizzo del dispositivo sul bus. PropertyBuffer punta a un ULONG.
L'interpretazione di questo indirizzo è specifica del bus. Il chiamante di questa routine deve chiamare nuovamente la routine per richiedere devicePropertyBusTypeGuid o eventualmente DevicePropertyLegacyBusType, in modo da poter interpretare l'indirizzo. Un valore di indirizzo di 0xFFFFFFFF indica che il driver del bus sottostante non ha fornito un indirizzo del bus per il dispositivo.
Nell'elenco seguente vengono descritte le informazioni archiviate da determinati driver del bus nella proprietàBuffer per i dispositivi figlio:
| Bus | Descrizione |
|---|---|
| 1394 | Non fornisce un indirizzo perché gli indirizzi sono volatili. Impostazione predefinita per 0xFFFFFFFF. |
| EISA | Numero slot (0-F). |
| IDE | Per un dispositivo IDE, l'indirizzo contiene l'ID di destinazione e il LUN. Per un canale IDE, l'indirizzo è zero o uno (0 = canale primario e 1 = canale secondario). |
| Isapnp | Non fornisce un indirizzo. Impostazione predefinita per 0xFFFFFFFF. |
| Scheda PC (PCMCIA) | Numero di socket (in genere 0x00 o 0x40). |
| PCI | Numero di dispositivo nella parola alta e numero di funzione nella parola bassa. |
| SCSI | ID di destinazione. |
| USB | Il numero della porta. |
DevicePropertyBootConfiguration
Richiede le risorse hardware assegnate al dispositivo dal firmware, in formato non elaborato. PropertyBuffer punta a una struttura CM_RESOURCE_LIST .
DevicePropertyBootConfigurationTranslated
Le risorse hardware assegnate al dispositivo dal firmware, in formato tradotto. PropertyBuffer punta a una struttura CM_RESOURCE_LIST .
DevicePropertyBusNumber
Richiede il numero di bus legacy del bus a cui è connesso il dispositivo. PropertyBuffer punta a un ULONG.
DevicePropertyBusTypeGuid
Richiede il GUID per il bus a cui è connesso il dispositivo. I GUID del tipo di bus definiti dal sistema sono elencati nel file di intestazione Wdmguid.h. PropertyBuffer punta a un GUID, ovvero una struttura a 16 byte che contiene il GUID in formato binario.
DevicePropertyClassGuid
Richiede il GUID per la classe di installazione del dispositivo. PropertyBuffer punta a una matrice con terminazione NULL di WCHAR. Questa routine restituisce il GUID in un formato stringa come indicato di seguito, dove ogni "c" rappresenta un carattere esadecimale: {cccccccc-cccc-cccc-cccccc}
DevicePropertyClassName
Richiede il nome della classe di installazione del dispositivo, in formato di testo. PropertyBuffer punta a una stringa WCHAR con terminazione NULL.
DevicePropertyCompatibleIDs
Richiede gli ID compatibili segnalati dal dispositivo. PropertyBuffer punta a un valore di REG_MULTI_SZ.
DevicePropertyDeviceDescription
Richiede una stringa che descrive il dispositivo, ad esempio "Mouse porta Microsoft PS/2", in genere definito dal produttore. PropertyBuffer punta a una stringa WCHAR con terminazione NULL.
DevicePropertyDriverKeyName
Richiede il nome della chiave del Registro di sistema specifica del driver. PropertyBuffer punta a una stringa WCHAR con terminazione NULL.
DevicePropertyEnumeratorName
Richiede il nome dell'enumeratore per il dispositivo, ad esempio "PCI" o "root". PropertyBuffer punta a una stringa WCHAR con terminazione NULL.
DevicePropertyFriendlyName
Richiede una stringa che può essere usata per distinguere tra due dispositivi simili, in genere definiti dal programma di installazione della classe. PropertyBuffer punta a una stringa WCHAR con terminazione NULL.
DevicePropertyHardwareID
Richiede gli ID hardware forniti dal dispositivo che identificano il dispositivo. PropertyBuffer punta a un valore di REG_MULTI_SZ.
DevicePropertyInstallState
Richiede lo stato di installazione del dispositivo. Lo stato di installazione viene restituito come valore di enumerazione DEVICE_INSTALL_STATE .
DevicePropertyLegacyBusType
Richiede il tipo di bus, ad esempio PCIBus o PCMCIABus. PropertyBuffer punta a un valore di enumerazione INTERFACE_TYPE .
DevicePropertyLocationInformation
Richiede informazioni sulla posizione del dispositivo sul bus; l'interpretazione di queste informazioni è specifica del bus. PropertyBuffer punta a una stringa WCHAR con terminazione NULL.
DevicePropertyManufacturer
Richiede una stringa che identifica il produttore del dispositivo. PropertyBuffer punta a una stringa WCHAR con terminazione NULL.
DevicePropertyPhysicalDeviceObjectName
Richiede il nome dell'oggetto PDO per questo dispositivo. PropertyBuffer punta a una stringa WCHAR con terminazione NULL.
DevicePropertyRemovalPolicy
Richiede i criteri di rimozione correnti del dispositivo. Il sistema operativo usa questo valore come hint per determinare come il dispositivo viene normalmente rimosso. Il parametro PropertyBuffer punta a un valore di enumerazione DEVICE_REMOVAL_POLICY .
DevicePropertyUINumber
Richiede un numero associato al dispositivo che può essere visualizzato nell'interfaccia utente. PropertyBuffer punta a un valore ULONG.
Questo numero è in genere un numero di slot percepito dall'utente, ad esempio un numero stampato accanto allo slot sulla scheda o un altro numero che rende più semplice l'individuazione del dispositivo fisico per l'utente. Se il dispositivo si trova su un bus che non ha alcuna convenzione di numero di interfaccia utente o se il driver del bus per il dispositivo non è in grado di determinare il numero di interfaccia utente, questo valore è 0xFFFFFFFF.
[in] BufferLength
Specifica le dimensioni, in byte, del chiamante fornito dal chiamante PropertyBuffer.
[out, optional] PropertyBuffer
Puntatore a un buffer fornito dal chiamante per ricevere le informazioni sulla proprietà. Il buffer può essere allocato dalla memoria pagable. Il tipo del buffer è determinato da 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 PropertyBuffer era troppo piccolo. ResultLength punta alla lunghezza del buffer richiesta. |
| STATUS_INVALID_PARAMETER_2 | DeviceProperty specificato non è una delle proprietà gestite da questa routine. |
| STATUS_INVALID_DEVICE_REQUEST | Probabilmente indica che il valore deviceObject specificato non era un puntatore PDO valido. |
Commenti
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 DeviceProperty , possono essere necessarie due o più chiamate a IoGetDeviceProperty per determinare l'oggetto BufferLength richiesto. La prima chiamata deve usare un valore di ipotesi migliore. Se lo stato restituito è STATUS_BUFFER_TOO_SMALL, il driver deve liberare il buffer corrente, allocare un buffer delle dimensioni restituite in ResultLength e 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 le proprietà DevicePropertyBusNumber, DevicePropertyBusTypeGuid e DevicePropertyLegacyBusType per distinguere tra gli autobus.
Requisiti
| 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) |