Função IoCreateDevice (wdm.h)
A rotina IoCreateDevice cria um objeto de dispositivo para uso por um driver.
Sintaxe
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
);
Parâmetros
[in] DriverObject
Ponteiro para o objeto driver do chamador. Cada driver recebe um ponteiro para seu objeto driver em um parâmetro para sua rotina DriverEntry . Os drivers de função e filtro do WDM também recebem um ponteiro de objeto de driver em suas rotinas AddDevice .
[in] DeviceExtensionSize
Especifica o número determinado pelo driver de bytes a serem alocados para a extensão do dispositivo do objeto do dispositivo. A estrutura interna da extensão do dispositivo é definida pelo driver.
[in, optional] DeviceName
Opcionalmente, aponta para um buffer que contém uma cadeia de caracteres Unicode terminada em nulo que nomeia o objeto do dispositivo. A cadeia de caracteres deve ser um nome de caminho completo. Os drivers de função e filtro WDM não nomeia seus objetos de dispositivo. Para obter mais informações, consulte Objetos de dispositivo nomeados.
Se um nome de dispositivo não for fornecido (ou seja, DeviceName é NULL), o objeto de dispositivo criado por IoCreateDevice não terá (e não pode) uma DACL (lista de controle de acesso discricionário) associada a ele. Para obter informações adicionais, consulte Descritores de segurança.
[in] DeviceType
Especifica uma das constantes FILE_DEVICE_XXX definidas pelo sistema que indicam o tipo de dispositivo (como FILE_DEVICE_DISK ou FILE_DEVICE_KEYBOARD) ou um valor definido pelo fornecedor para um novo tipo de dispositivo. Para obter mais informações, consulte Especificando tipos de dispositivo.
[in] DeviceCharacteristics
Especifica uma ou mais constantes definidas pelo sistema, ORed juntas, que fornecem informações adicionais sobre o dispositivo do driver. Para obter uma lista de possíveis características do dispositivo, consulte DEVICE_OBJECT. Para obter mais informações sobre como especificar características do dispositivo, consulte Especificando características do dispositivo. A maioria dos drivers especifica FILE_DEVICE_SECURE_OPEN para esse parâmetro.
[in] Exclusive
Especifica se o objeto do dispositivo representa um dispositivo exclusivo. A maioria dos drivers define esse valor como FALSE. Para obter mais informações sobre acesso exclusivo, consulte Especificando o acesso exclusivo a objetos de dispositivo.
[out] DeviceObject
Ponteiro para uma variável que recebe um ponteiro para a estrutura de DEVICE_OBJECT recém-criada. A estrutura de DEVICE_OBJECT é alocada do pool nãopagado. A extensão de dispositivo do objeto do dispositivo está zerado.
Retornar valor
IoCreateDevice retorna STATUS_SUCCESS com êxito ou o código de erro NTSTATUS apropriado em caso de falha. Uma lista parcial dos códigos de falha retornados por essa função inclui:
STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_COLLISION
Comentários
IoCreateDevice cria um objeto de dispositivo e retorna um ponteiro para o objeto . O chamador é responsável por excluir o objeto quando ele não é mais necessário chamando IoDeleteDevice.
IoCreateDevice só pode ser usado para criar um objeto de dispositivo sem nome ou um objeto de dispositivo nomeado para o qual um descritor de segurança é definido por um arquivo INF. Caso contrário, os drivers devem usar IoCreateDeviceSecure para criar objetos de dispositivo nomeados. Para obter mais informações, consulte Criando um objeto device. O chamador é responsável por definir determinados membros do objeto de dispositivo retornado. Para obter mais informações, consulte Inicializando um objeto de dispositivo e a documentação específica do tipo de dispositivo para seu dispositivo.
Tenha cuidado para especificar os valores DeviceType e DeviceCharacteristics nos parâmetros corretos. Ambos os parâmetros usam constantes FILE_XXX definidas pelo sistema e alguns gravadores de driver especificam os valores nos parâmetros errados por engano.
Um sistema de arquivos remoto que cria um objeto de dispositivo nomeado para um redirecionador de rede e que se registra usando FsRtlRegisterUncProvider, deve especificar FILE_REMOTE_DEVICE como uma das opções no parâmetro DeviceCharacteristics de IoCreateDevice.
Os objetos de dispositivo para discos, fitas, CD-ROMs e discos de RAM recebem um VPB (Bloco de Parâmetros de Volume) inicializado para indicar que o volume nunca foi montado no dispositivo.
Se a chamada de um driver para IoCreateDevice retornar um erro, o driver deverá liberar todos os recursos alocados para esse dispositivo.
Requisitos
| Requisito | Valor |
|---|---|
| Plataforma de Destino | Universal |
| Cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | IRQL <= APC_LEVEL |
| Regras de conformidade de DDI | AddDevice(wdm), CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice(kmdf) |