Funzione WdmlibIoCreateDeviceSecure (wdmsec.h)

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 al relativo oggetto driver in un parametro alla routine DriverEntry. I driver di funzione e filtro WDM ricevono anche 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 costantiFILE_DEVICE_ 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 un 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 deriva 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 subset di SdDL (Security Descriptor Definition Language). Viene fornito anche 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 override per il DefaultSDDLString, DeviceType, DeviceCharacteristicse parametri esclusivi.

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:

Osservazioni

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 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 garantisce che il descrittore di sicurezza impostato dal file INF usi WdmlibIoCreateDeviceSecure. Per altre informazioni, vedere Creazione di un oggetto dispositivo. Il chiamante è responsabile dell'impostazione di determinati membri dell'oggetto dispositivo restituito. Per altre informazioni, vedere Inizializzazione di un oggetto dispositivo e la 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 flag e l'inizializzazione dell'estensione del dispositivo con qualsiasi informazione definita dal driver. Per altre operazioni necessarie nei nuovi oggetti dispositivo, vedere Inizializzazione di un oggetto dispositivo e la 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 installazione dei dispositivi, vedere Classi di installazione dei dispositivi. 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 in Microsoft Windows SDK.

I driver del bus WDM che gestiscono dispositivi con supporto per la modalità non elaborata possono specificare la classe di installazione 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 di 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.

Fabbisogno

Vedere anche

DEVICE_OBJECT

IoAttachDevice

IoAttachDeviceToDeviceStack

IoCreateDevice

IoCreateSymbolicLink

IoDeleteDevice