Função IoCreateDevice (wdm.h)

Artigo
03/05/2024

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)