Funzione IoCreateDevice (wdm.h)

Articolo
02/27/2024

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)