Funzione IoRegisterDeviceInterface (wdm.h)

La routine IoRegisterDeviceInterface registra una classe di interfaccia del 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à (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 di bus, ad esempio swenum, che è un driver del bus che usa le 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 stringhe 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 come 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
STATUS_INVALID_DEVICE_REQUEST
I parametri non sono validi. Le possibilità includono che PhysicalDeviceObject non punta a un PDO valido o che la stringa ReferenceString contiene un carattere non valido.

Commenti

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. Una funzione o un driver di 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 persistente 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 SymbolicLinkName e restituisce lo stato di esito positivo informativo STATUS_OBJECT_NAME_EXISTS.

La maggior parte dei driver usa una stringa di riferimento NULL per un'istanza dell'interfaccia del dispositivo. Se un driver usa una stringa di riferimento non NULL , 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 elemento ReferenceStringNULL per evitare conflitti con altri driver nello stack di dispositivi.

I chiamanti di questa routine non sono necessari per 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.

Requisiti

   
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 HwStorPortProhibitedDDDIs(storport), IrqlIoPassive3(wdm), PowerIrpDDis(wdm)

Vedi anche

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString