Funzione IoRegisterDeviceInterface (wdm.h)
La routine IoRegisterDeviceInterface registra una classe di interfaccia dispositivo , se non è stata registrata in precedenza e crea una nuova istanza della classe di interfaccia, che un driver può successivamente abilitare per l'uso da parte di applicazioni o altri componenti di sistema.
Sintassi
NTSTATUS IoRegisterDeviceInterface(
[in] PDEVICE_OBJECT PhysicalDeviceObject,
[in] const GUID *InterfaceClassGuid,
[in, optional] PUNICODE_STRING ReferenceString,
[out] PUNICODE_STRING SymbolicLinkName
);
Parametri
[in] PhysicalDeviceObject
Puntatore al PDO per il dispositivo.
[in] InterfaceClassGuid
Puntatore al GUID della classe che identifica la funzionalità (la classe dell'interfaccia del dispositivo) registrata.
[in, optional] ReferenceString
Facoltativamente, punta a un UNICODE_STRING. La stringa non deve contenere caratteri separatori di percorso ("/" o "\"). I driver di funzione specificano in genere NULL per questo parametro. I driver di filtro devono specificare NULL.
Le stringhe di riferimento vengono usate solo da alcuni driver del bus, ad esempio swenum, che è un driver bus che usa istanze dell'interfaccia del dispositivo come segnaposto per i dispositivi software creati su richiesta. Quando viene aperta un'istanza di un'interfaccia, il gestore di I/O passa la stringa di riferimento dell'istanza al driver. La stringa diventa parte del nome dell'istanza dell'interfaccia (come componente del percorso aggiunto). Il driver può quindi usare la stringa di riferimento per distinguere due istanze di interfaccia della stessa classe per un singolo dispositivo.
Nei sistemi Microsoft Windows 98/Me il valore ReferenceString non può essere più di MAX_PATH caratteri. Non esiste alcun limite di lunghezza per Windows 2000 e versioni successive di Windows.
[out] SymbolicLinkName
Puntatore a una struttura di stringa Unicode allocata dal chiamante. Se questa routine ha esito positivo, inizializza la stringa Unicode e alloca il buffer stringa contenente il percorso in modalità kernel al collegamento simbolico per un'istanza della classe di interfaccia del dispositivo specificata.
Il chiamante deve trattare SymbolicLinkName opaco e non deve disassemblarlo.
Il chiamante è responsabile della liberazione di SymbolicLinkName con RtlFreeUnicodeString quando non è più necessario.
Valore restituito
IoRegisterDeviceInterface restituisce STATUS_SUCCESS se la chiamata ha avuto esito positivo. I valori restituiti di errore possibili includono quanto segue.
| Codice restituito | Descrizione |
|---|---|
|
I parametri non sono validi. Le possibilità includono che |
Osservazioni
IoRegisterDeviceInterface registra una classe di interfaccia del dispositivo, se non è stata registrata in precedenza e crea una nuova istanza della classe di interfaccia. Un driver può chiamare questa routine più volte per un determinato dispositivo per registrare diverse classi di interfaccia e creare istanze delle classi. Un driver di funzione o filtro registra in genere le interfacce del dispositivo nella routine AddDevice. Ad esempio, un driver di volume a tolleranza di errore potrebbe registrare un'istanza di un'interfaccia del volume a tolleranza di errore e un'istanza di un'interfaccia del volume per un determinato volume.
Se la classe dell'interfaccia del dispositivo non è stata registrata in precedenza, il gestore di I/O crea una chiave del Registro di sistema, insieme all'archiviazione permanente specifica dell'istanza nella chiave. I driver possono accedere a questa risorsa di archiviazione permanente usando IoOpenDeviceInterfaceRegistryKey.
Un driver registra un'istanza di interfaccia una sola volta e quindi chiama IoSetDeviceInterfaceState per abilitare e disabilitare l'interfaccia.
Le interfacce registrate vengono mantenute tra i riavvii del sistema operativo. Se l'interfaccia specificata è già registrata, il gestore di I/O passa il nome in SimbolicLinkName e restituisce lo stato di esito positivo informativo STATUS_OBJECT_NAME_EXISTS.
La maggior parte dei driver usa un NULL stringa di riferimento per un'istanza dell'interfaccia del dispositivo. Se un driver usa una stringa di riferimento nonNULL, deve eseguire operazioni aggiuntive, inclusa la gestione del proprio spazio dei nomi e della sicurezza. Un driver di filtro che espone un'interfaccia del dispositivo deve usare un NULLReferenceString per evitare conflitti con altri driver nello stack di dispositivi.
I chiamanti di questa routine non sono tenuti a rimuovere la registrazione per un'interfaccia del dispositivo quando non è più necessaria. Le registrazioni dell'interfaccia del dispositivo possono essere rimosse dalla modalità utente, se necessario.
I chiamanti di IoRegisterDeviceInterface devono essere in esecuzione in IRQL = PASSIVE_LEVEL nel contesto di un thread di sistema.
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 (vedere la sezione Osservazioni) |
| regole di conformità DDI | HwStorPortProhibitedDDIs(storport), IrqlIoPassive3(wdm), PowerIrpDDis(wdm) |