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 del bus, ad esempio swenum, che è un driver del 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, la gestione 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 tra due istanze dell'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 SimbolicLinkName come opaco e non deve smontarlo.

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 degli errori 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. Un driver di funzione o filtro registra in genere le interfacce del dispositivo nella routine AddDevice . Ad esempio, un driver del volume a tolleranza di errore può registrare un'istanza di un'interfaccia a tolleranza di errore e un'istanza di un'interfaccia del volume per un volume specifico.

Se la classe dell'interfaccia del dispositivo non è stata registrata in precedenza, la gestione 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 persistente usando IoOpenDeviceInterfaceRegistryKey.

Un driver registra un'istanza dell'interfaccia una 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, la gestione I/O passa il nome in SimbolicoLinkName 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 dello spazio dei nomi e della sicurezza. Un driver di filtro che espone un'interfaccia del dispositivo deve usare un riferimento NULLString 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ù necessario. 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

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

Vedi anche

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString