Функция WdfDpcCreate (wdfdpc.h)

Статья
08/08/2023

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

Метод WdfDpcCreate создает объект DPC платформы и регистрирует функцию обратного вызова EvtDpcFunc .

Синтаксис

NTSTATUS WdfDpcCreate(
  [in]  PWDF_DPC_CONFIG        Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFDPC                 *Dpc
);

Параметры

[in] Config

Указатель на структуру, выделенную вызывающим объектом WDF_DPC_CONFIG .

[in] Attributes

Указатель на структуру, выделенную вызывающим объектом WDF_OBJECT_ATTRIBUTES , которая задает атрибуты для нового объекта DPC.

[out] Dpc

Указатель на расположение, которое получает дескриптор нового объекта DPC платформы.

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

WdfDpcCreate возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае метод может вернуть одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_PARAMETER	Указан недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES	Не удалось выделить объект DPC.
STATUS_WDF_PARENT_NOT_SPECIFIED	Родительский объект не указан в структуре WDF_OBJECT_ATTRIBUTES .
STATUS_INVALID_DEVICE_REQUEST	Элемент ParentObject структуры WDF_OBJECT_ATTRIBUTES не ссылается на объект устройства платформы или объект, цепочка родителей которого приводит к объекту устройства платформы.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Элемент AutomaticSerialization структуры WDF_DPC_CONFIG имеет значение TRUE, а уровень выполнения родительского объекта — WdfExecutionLevelPassive.

Список других возвращаемых значений, которые может возвращать метод WdfDpcCreate , см. в разделе Ошибки создания объектов платформы.

Этот метод также может возвращать другие значения NTSTATUS.

Когда драйвер создает объект DPC, он должен указать родительский объект в элементе ParentObjectструктуры WDF_OBJECT_ATTRIBUTES . Родительским объектом может быть объект устройства платформы или любой объект, цепочка родителей которого ведет к объекту устройства платформы. Платформа удалит объект DPC при удалении объекта устройства.

Вызов WdfDpcCreate создает объект DPC платформы и регистрирует функцию обратного вызова EvtDpcFunc . Чтобы запланировать выполнение функции обратного вызова, драйвер должен вызвать WdfDpcEnqueue.

Если драйвер предоставляет функции обратного вызова EvtCleanupCallback или EvtDegradCallback для объекта таймера платформы, обратите внимание, что платформа вызывает эти функции обратного вызова в IRQL = PASSIVE_LEVEL.

Дополнительные сведения об использовании объектов DPC см. в разделе Обслуживание прерывания.

Примеры

В следующем примере кода инициализируется структура WDF_DPC_CONFIG_INIT , а затем создается объект DPC.

WDF_DPC_CONFIG dpcConfig;
WDF_OBJECT_ATTRIBUTES dpcAttributes;
NTSTATUS status;

WDF_DPC_CONFIG_INIT(
                    &dpcConfig,
                    MyEvtDpcFunc
                    );
dpcConfig.AutomaticSerialization = TRUE;
WDF_OBJECT_ATTRIBUTES_INIT(&dpcAttributes);
dpcAttributes.ParentObject = pDevExt->WdfDevice;
status = WdfDpcCreate(
                      &dpcConfig,
                      &dpcAttributes,
                      &pDevExt->CompleteWriteDpc
                      );
if (!NT_SUCCESS(status)) {
    return status;
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Верхняя часть	wdfdpc.h (включая Wdf.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки Платформы).
IRQL	<=DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)