Função IoCreateDevice (wdm.h)

Artigo
12/21/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 de driver em um parâmetro para sua rotina de DriverEntry. Os drivers de função e filtro do WDM também recebem um ponteiro de objeto de driver em suas rotinas de AddDevice.

[in] DeviceExtensionSize

Especifica o número determinado pelo driver de bytes a serem alocados para o de extensão de 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 estiver NULL), o objeto de dispositivo criado por IoCreateDevice não terá (e não pode) uma DACL (lista de controle de acesso discricionária) associada a ela. 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 do dispositivo do objeto do dispositivo está zerado.

Valor de retorno

IoCreateDevice retorna STATUS_SUCCESS com êxito ou o código de erro NTSTATUS apropriado sobre falha. Uma lista parcial dos códigos de falha retornados por essa função inclui:

STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_COLLISION

Observações

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 de dispositivo. 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 DeviceType e DeviceCharacteristics valores nos parâmetros corretos. Ambos os parâmetros usam constantes de XXX FILE_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.

Objetos de dispositivo para discos, fitas, CD-ROMs e discos de RAM recebem um VPB (Bloco de Parâmetros de Volume) que é 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
da Plataforma de Destino	Universal
cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
regras de conformidade de DDI	AddDevice(wdm), CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice(kmdf)

Consulte também

DEVICE_OBJECT

FsRtlRegisterUncProvider

IoAttachDevice

IoAttachDeviceToDeviceStack

IoCreateDeviceSecure

IoCreateSymbolicLink

IoDeleteDevice

Compartilhar via