Funzione IoCreateDevice (wdm.h)
La routine IoCreateDevice crea un oggetto dispositivo da usare da un driver.
Sintassi
NTSTATUS IoCreateDevice(
[in] PDRIVER_OBJECT DriverObject,
[in] ULONG DeviceExtensionSize,
[in, optional] PUNICODE_STRING DeviceName,
[in] DEVICE_TYPE DeviceType,
[in] ULONG DeviceCharacteristics,
[in] BOOLEAN Exclusive,
[out] 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 per la routine DriverEntry . La funzione WDM e i driver di filtro ricevono anche un puntatore a oggetti driver nelle routine AddDevice .
[in] DeviceExtensionSize
Specifica il numero determinato di 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 contenente una stringa Unicode con terminazione null che nomi l'oggetto dispositivo. La stringa deve essere un nome completo del percorso. I driver di filtro e funzione WDM non denominano i relativi oggetti dispositivo. Per altre informazioni, vedere Oggetti dispositivo denominati.
Se un nome del dispositivo non viene fornito (ovvero DeviceName è NULL), l'oggetto dispositivo creato da IoCreateDevice non avrà un elenco di controllo di accesso discrezionale associato. Per altre informazioni, vedere Descrittori di sicurezza.
[in] DeviceType
Specifica una delle costanti FILE_DEVICE_XXX definite dal sistema che indicano il tipo di dispositivo (ad esempio FILE_DEVICE_DISK o FILE_DEVICE_KEYBOARD) o un valore definito dal fornitore per un nuovo tipo di dispositivo. Per altre informazioni, vedere Specifica dei tipi di dispositivo.
[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 sull'accesso esclusivo, vedere Specifica dell'accesso esclusivo agli oggetti dispositivo.
[out] DeviceObject
Puntatore a una variabile che riceve un puntatore alla struttura DEVICE_OBJECT appena creata. La struttura DEVICE_OBJECT viene allocata dal pool non a pagina. L'estensione del dispositivo dell'oggetto dispositivo è zero.
Valore restituito
IoCreateDevice 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 restituiti da questa funzione include:
STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_COLLISION
Commenti
IoCreateDevice crea un oggetto dispositivo e restituisce un puntatore all'oggetto. Il chiamante è responsabile dell'eliminazione dell'oggetto quando non è più necessario chiamando IoDeleteDevice.
IoCreateDevice può essere usato solo per creare un oggetto dispositivo senza nome o un oggetto dispositivo denominato per il quale un descrittore di sicurezza è impostato da un file INF. In caso contrario, i driver devono usare IoCreateDeviceSecure per creare oggetti dispositivo denominati. 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 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.
Un file system remoto che crea un oggetto dispositivo denominato per un reindirizzamento di rete e che registra l'uso di FsRtlRegisterUncProvider, deve specificare FILE_REMOTE_DEVICE come una delle opzioni nel parametro DeviceCharacteristics di IoCreateDevice.
Gli oggetti dispositivo per dischi, nastri, cd-RO e dischi RAM vengono assegnati a un blocco di parametri del volume (VPB) che indica che il volume non è mai stato montato nel dispositivo.
Se la chiamata di un driver a IoCreateDevice restituisce un errore, il driver deve rilasciare qualsiasi risorsa allocata per tale dispositivo.
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Universale |
| Intestazione | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Libreria | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | IRQL <= APC_LEVEL |
| Regole di conformità DDI | AddDevice(wdm), CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDDDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice(kmdf) |