Condividi tramite


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)

Vedi anche

CM_RESOURCE_LIST

DEVICE_REMOVAL_POLICY

ExAllocatePoolWithTag

GUID

INTERFACE_TYPE

IO_RESOURCE_REQUIREMENTS_LIST