Функция WdfControlDeviceInitAllocate (wdfcontrol.h)

Статья
08/08/2023

[Относится только к KMDF]

Метод WdfControlDeviceInitAllocate выделяет WDFDEVICE_INIT структуру, используемую драйвером при создании нового объекта управляющего устройства.

Синтаксис

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

Параметры

[in] Driver

Дескриптор объекта драйвера платформы.

[in] SDDLString

Указатель на структуру UNICODE_STRING , описывающую строку Юникода. Эта строка представляет собой представление дескриптора безопасности (SDDL) дескриптора безопасности. Дополнительные сведения см. в разделе "Примечания".

Возвращаемое значение

WdfControlDeviceInitAllocate возвращает указатель на структуру, выделенную платформой WDFDEVICE_INIT , если операция выполнена успешно. В противном случае метод возвращает значение NULL.

Если вы хотите, чтобы драйвер создавал объект управляющего устройства, драйвер должен вызвать WdfControlDeviceInitAllocate , чтобы получить WDFDEVICE_INIT структуру, которую он может передать в WdfDeviceCreate.

Драйвер может указать параметр безопасности с помощью подмножества SDDL. Файл Wdmsec.h определяет набор констант в формате SDDL_DEVOBJ_Xxx, которые можно использовать. Дополнительные сведения о дескрипторах безопасности и SDDL см. в разделе Защита объектов устройств.

Метод WdfDeviceInitAssignSDDLString перезаписывает параметр безопасности , если он есть, заданный WdfControlDeviceInitAllocate .

Дополнительные сведения о вызове WdfControlDeviceInitAllocate см. в разделе Использование объектов управления устройствами.

Примеры

В следующем примере кода выделяется структура DEVICE_INIT, назначается имя объекта устройства, регистрируется функция обратного вызова уведомления о завершении работы и создается управляющий объект устройства. Более сложный пример использования WdfControlDeviceInitAllocate см. в примере драйвера NONPNP или примере драйвера 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);

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Верхняя часть	wdfcontrol.h (включая Wdf.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки Платформы).
IRQL	PASSIVE_LEVEL
Правила соответствия 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)