Funzione WdmlibIoCreateDeviceSecure (wdmsec.h)

Articolo
03/08/2023

La funzione WdmlibIoCreateDeviceSecure (o IoCreateDeviceSecure) crea un oggetto dispositivo denominato e applica le impostazioni di sicurezza specificate.

Sintassi

NTSTATUS WdmlibIoCreateDeviceSecure(
  [in]           PDRIVER_OBJECT   DriverObject,
  [in]           ULONG            DeviceExtensionSize,
  [in, optional] PUNICODE_STRING  DeviceName,
  [in]           DEVICE_TYPE      DeviceType,
  [in]           ULONG            DeviceCharacteristics,
  [in]           BOOLEAN          Exclusive,
  [in]           PCUNICODE_STRING DefaultSDDLString,
  [in, optional] LPCGUID          DeviceClassGuid,
                 PDEVICE_OBJECT   *DeviceObject
);

Parametri

[in] DriverObject

Puntatore all'oggetto driver per il chiamante. Ogni driver riceve un puntatore all'oggetto driver in un parametro per la routine DriverEntry . Anche i driver di funzione e filtro WDM ricevono un puntatore a oggetti driver nelle routine AddDevice .

[in] DeviceExtensionSize

Specifica il numero di byte determinato dal driver da allocare per l'estensione del dispositivo dell'oggetto dispositivo. La struttura interna dell'estensione del dispositivo è definita dal driver.

[in, optional] DeviceName

Facoltativamente punta a un buffer che contiene una stringa Unicode con terminazione Null che assegna un nome all'oggetto dispositivo. La stringa deve essere un nome di percorso completo. Se non viene specificato un nome, il flag FILE_AUTOGENERATED_DEVICE_NAME deve essere presente nel parametro DeviceCharacteristics . Per creare un oggetto dispositivo senza nome, usare la routine IoCreateDevice .

[in] DeviceType

Specifica una delle costanti FILE_DEVICE_XXX definite dal sistema che indicano il tipo di dispositivo (ad esempio FILE_DEVICE_DISK, FILE_DEVICE_KEYBOARD e così via) o un valore definito dal fornitore per un nuovo tipo di dispositivo. Per altre informazioni, vedere Specifica dei tipi di dispositivo. Poiché un driver del bus potrebbe non avere informazioni sul tipo di un dispositivo, è possibile specificare un valore del tipo di dispositivo per un PDO in una direttiva INF AddReg.

[in] DeviceCharacteristics

Specifica una o più costanti definite dal sistema, ORed insieme, che forniscono informazioni aggiuntive sul dispositivo del driver. Per un elenco delle possibili caratteristiche del dispositivo, vedere DEVICE_OBJECT. Per altre informazioni su come specificare le caratteristiche del dispositivo, vedere Specifica delle caratteristiche del dispositivo. La maggior parte dei driver specifica FILE_DEVICE_SECURE_OPEN per questo parametro.

[in] Exclusive

Specifica se l'oggetto dispositivo rappresenta un dispositivo esclusivo. La maggior parte dei driver imposta questo valore su FALSE. Per altre informazioni, vedere Specifica dell'accesso esclusivo agli oggetti dispositivo.

[in] DefaultSDDLString

Specifica una rappresentazione di stringa per le impostazioni di sicurezza predefinite dell'oggetto dispositivo. La sicurezza applicata all'oggetto dispositivo è derivata da questa stringa, a meno che l'amministratore di sistema non inserisca un override nella sezione del Registro di sistema identificata dal parametro DeviceClassGuid .

L'impostazione di sicurezza viene specificata in un sottoinsieme di SDDL (Security Descriptor Definition Language). Viene inoltre fornito un set di costanti predefinite (SDDL_DEVOBJ_XXX). Per altre informazioni, vedere Protezione degli oggetti dispositivo.

[in, optional] DeviceClassGuid

Puntatore a un GUID che identifica una sezione del Registro di sistema contenente possibili sostituzioni per i parametri DefaultSDDLString, DeviceType, DeviceCharacteristics ed Exclusive .

Nota È sempre necessario specificare un GUID di classe personalizzato. Non è consigliabile specificare un GUID di classe esistente. Se si specifica un GUID di classe esistente, altri driver che tentano di specificare che il GUID della classe esistente potrebbe non essere installato o potrebbe non essere installato con impostazioni di sicurezza non corrette.

DeviceObject

Puntatore a una variabile che riceve un puntatore alla struttura DEVICE_OBJECT appena creata. La struttura DEVICE_OBJECT viene allocata dal pool non di paging.

Valore restituito

WdmlibIoCreateDeviceSecure restituisce STATUS_SUCCESS in caso di esito positivo o il codice di errore NTSTATUS appropriato in caso di errore. Un elenco parziale dei codici di errore che possono essere restituiti da questa funzione includono:

Commenti

WdmlibIoCreateDeviceSecure crea un oggetto dispositivo denominato, applica le impostazioni di sicurezza specificate e restituisce un puntatore all'oggetto . Il chiamante è responsabile dell'eliminazione dell'oggetto quando non è più necessario chiamando IoDeleteDevice.

Questa routine non fa parte del sistema operativo. I driver possono usare la routine collegando Wdmsec.lib in Microsoft Windows 2000 e versioni successive di Windows. (La libreria Wdmsec.lib è stata fornita prima con le edizioni Microsoft Windows XP Service Pack 1 [SP1] e Windows Server 2003 del Driver Development Kit [DDK] e viene fornito anche con Windows Driver Kit [WDK].)

Qualsiasi driver che crea un oggetto dispositivo denominato che non è garantito che il descrittore di sicurezza sia impostato dal file INF deve usare WdmlibIoCreateDeviceSecure. Per altre informazioni, vedere Creazione di un oggetto Device. Il chiamante è responsabile dell'impostazione di determinati membri dell'oggetto dispositivo restituito. Per altre informazioni, vedere Inizializzazione di un oggetto dispositivo e documentazione specifica del tipo di dispositivo per il dispositivo.

Prestare attenzione a specificare i valori DeviceType e DeviceCharacteristics nei parametri corretti. Entrambi i parametri usano costanti FILE_XXX definite dal sistema e alcuni writer di driver specificano i valori nei parametri errati per errore.

Il chiamante è responsabile dell'impostazione di determinati campi nell'oggetto dispositivo restituito, ad esempio il campo Flags e per l'inizializzazione dell'estensione del dispositivo con qualsiasi informazione definita dal driver. Per altre operazioni necessarie sui nuovi oggetti dispositivo, vedere Inizializzazione di un oggetto dispositivo e documentazione specifica del tipo di dispositivo per il dispositivo.

Il GUID specificato dal parametro DeviceClassGuid determina la classe di installazione del dispositivo per l'oggetto dispositivo. Per altre informazioni sulle classi di configurazione dei dispositivi, vedere Classi di installazione del dispositivo. I chiamanti devono fornire un valore in modo che gli amministratori di sistema possano modificare le impostazioni di sicurezza per il dispositivo (ad esempio, per negare l'accesso a determinati utenti). Per altre informazioni, vedere Impostazione delle proprietà del Registro oggetti dispositivo dopo l'installazione.

I driver non WDM specificano un nuovo GUID, non già in uso da una classe di configurazione del dispositivo esistente. Generare un nuovo GUID usando lo strumento GuidGen.exe incluso nel Microsoft Windows SDK.

I driver del bus WDM che gestiscono dispositivi che supportano la modalità non elaborata possono specificare la classe di configurazione del dispositivo, ma solo se tale classe è già stata creata. In caso contrario, creare un nuovo GUID.

Agli oggetti dispositivo per dischi, nastri, CD-ROm e dischi RAM viene assegnato un blocco di parametri del volume (VPB) che viene inizializzato per indicare che il volume non è mai stato montato nel dispositivo.

Se la chiamata di un driver a WdmlibIoCreateDeviceSecure restituisce un errore, il driver deve rilasciare tutte le risorse allocate per tale dispositivo.

Requisiti

Requisito	Valore
Client minimo supportato	Vedere la sezione Osservazioni.
Piattaforma di destinazione	Desktop
Intestazione	wdmsec.h (include Wdmsec.h)
Libreria	Wdmsec.lib
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	AddDevice(wdm), HwStorPortProhibitedDDDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice