Função WdfControlDeviceInitAllocate (wdfcontrol.h)

Artigo
08/08/2023

[Aplica-se somente ao KMDF]

O método WdfControlDeviceInitAllocate aloca uma estrutura WDFDEVICE_INIT que um driver usa ao criar um novo objeto de dispositivo de controle.

Sintaxe

PWDFDEVICE_INIT WdfControlDeviceInitAllocate(
  [in] WDFDRIVER            Driver,
  [in] const UNICODE_STRING *SDDLString
);

Parâmetros

[in] Driver

Um identificador para um objeto de driver de estrutura.

[in] SDDLString

Um ponteiro para uma estrutura UNICODE_STRING que descreve uma cadeia de caracteres Unicode. Essa cadeia de caracteres é uma representação de SDDL (Linguagem de Definição de Descritor de Segurança) de um descritor de segurança. Para obter mais informações, consulte a seção Comentários a seguir.

Retornar valor

WdfControlDeviceInitAllocate retorna um ponteiro para uma estrutura de WDFDEVICE_INIT alocada por estrutura, se a operação for bem-sucedida. Caso contrário, o método retornará NULL.

Comentários

Se você quiser que o driver crie um objeto de dispositivo de controle, o driver deve chamar WdfControlDeviceInitAllocate para obter uma estrutura WDFDEVICE_INIT que ele possa passar para WdfDeviceCreate.

Seu driver pode especificar uma configuração de segurança usando um subconjunto de SDDL. O arquivo Wdmsec.h define um conjunto de constantes formatadas em SDDL_DEVOBJ_Xxx que você pode usar. Para obter mais informações sobre descritores de segurança e SDDL, consulte Protegendo objetos de dispositivo.

O método WdfDeviceInitAssignSDDLString substitui a configuração de segurança, se houver, especificada por WdfControlDeviceInitAllocate .

Para obter mais informações sobre como chamar WdfControlDeviceInitAllocate, consulte Usando objetos de dispositivo de controle.

Exemplos

O exemplo de código a seguir aloca uma estrutura DEVICE_INIT, atribui um nome de objeto de dispositivo, registra uma função de retorno de chamada de notificação de desligamento e cria um objeto de dispositivo de controle. Para obter um exemplo mais complexo que usa WdfControlDeviceInitAllocate, consulte o driver de exemplo NONPNP ou o driver de exemplo NDISProt .

PWDFDEVICE_INIT  deviceInit = NULL;
NTSTATUS  status;
WDF_OBJECT_ATTRIBUTES  objectAttribs;

deviceInit = WdfControlDeviceInitAllocate(
                                          hDriver,
                                          &SDDL_DEVOBJ_SYS_ALL_ADM_RWX_WORLD_RW_RES_R
                                          );
if (deviceInit == NULL) {
    status = STATUS_INSUFFICIENT_RESOURCES;
    goto Error;
}
status = WdfDeviceInitAssignName(
                                 deviceInit,
                                 &ntDeviceName
                                 );
if (!NT_SUCCESS(status)) {
    WdfDeviceInitFree(deviceInit);
    deviceInit = NULL;
    goto Error;
}
WdfControlDeviceInitSetShutdownNotification(
                                            deviceInit,
                                            EvtShutdownNotification,
                                            WdfDeviceShutdown
                                            );
WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);

status = WdfDeviceCreate(
                         &deviceInit,
                         &objectAttribs,
                         &controlDevice
                         );
if (!NT_SUCCESS(status)) {
    WdfDeviceInitFree(deviceInit);
    deviceInit = NULL;
    goto Error;
}
WdfControlFinishInitializing(controlDevice);

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Cabeçalho	wdfcontrol.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.)
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	ControlDeviceInitAPI(kmdf), CtlDeviceFinishInitDeviceAdd(kmdf), CtlDeviceFinishInitDrEntry(kmdf), DoubleDeviceInitFree(kmdf), DriverCreate(kmdf), InitFreeDeviceCallback(kmdf), InitFreeDeviceCreate(kmdf), InitFreeDeviceCreateType2(kmdf), InitFreeDeviceCreateType4(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)