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 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 contenente una stringa Unicode con terminazione Null che denomina l'oggetto dispositivo. La stringa deve essere un nome di percorso completo. I driver di filtro e funzione WDM non denominano i relativi oggetti dispositivo. Per altre informazioni, vedere oggetti dispositivo denominati.

Se non viene specificato un nome di dispositivo ( ovvero DeviceName è NULL), l'oggetto dispositivo creato da IoCreateDevice non sarà (e non potrà) avere associato un elenco di controllo di accesso discrezionale (DACL). Per altre informazioni, vedere descrittori di sicurezza .

[in] DeviceType

Specifica una delle costanti FILE_DEVICE_ 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 di paging. 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

Osservazioni

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 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.

Un file system remoto che crea un oggetto dispositivo denominato per un redirector di rete e che esegue la registrazione usando FsRtlRegisterUncProvider, deve specificare FILE_REMOTE_DEVICE come una delle opzioni nel DeviceCharacteristics parametro di IoCreateDevice.

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 IoCreateDevice restituisce un errore, il driver deve rilasciare tutte le risorse allocate per tale dispositivo.

Fabbisogno

Vedere anche

DEVICE_OBJECT

FsRtlRegisterUncProvider

IoAttachDevice

IoAttachDeviceToDeviceStack

IoCreateDeviceSecure

IoCreateSymbolicLink

IoDeleteDevice