WdfDpcCreate 函式 (wdfdpc.h)

發行項
03/01/2024

[僅適用於 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。否則，方法可能會傳回下列其中一個值：

傳回碼	Description
STATUS_INVALID_PARAMETER	指定了無效的參數。
STATUS_INSUFFICIENT_RESOURCES	無法配置 DPC 物件。
STATUS_WDF_PARENT_NOT_SPECIFIED	WDF_OBJECT_ATTRIBUTES 結構中未指定父物件。
STATUS_INVALID_DEVICE_REQUEST	WDF_OBJECT_ATTRIBUTES 結構的ParentObject成員不會參考架構裝置物件或父系鏈結導致架構裝置物件的物件。
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	WDF_DPC_CONFIG 結構的 AutomaticSerialization 成員會設定為 TRUE，但父對象的執行層級會設定為 WdfExecutionLevelPassive。

如需 WdfDpcCreate 方法可能會傳回的其他傳回值清單，請參閱 Framework 物件建立錯誤。

這個方法也可能傳回其他 NTSTATUS值。

備註

驅動程式通常會從其 EvtDriverDeviceAdd 回呼函式內呼叫 WdfDpcCreate。

當驅動程式建立 DPC 物件時，必須在 WDF_OBJECT_ATTRIBUTES 結構的 ParentObject 成員中指定父物件。父物件可以是架構裝置物件，或是父系鏈結導致架構裝置物件的任何物件。架構會在刪除裝置物件時刪除 DPC 物件。

呼叫 WdfDpcCreate 會建立架構 DPC 物件，並註冊 EvtDpcFunc 回呼函式。若要排程回呼函式的執行，驅動程式必須呼叫 WdfDpcEnqueue。

如果您的驅動程式為架構定時器物件提供 EvtCleanupCallback 或 EvtDestroyCallback 回呼函式，請注意，架構會在 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;
}

規格需求

需求	值
目標平台	Universal
最小 KMDF 版本	1.0
標頭	wdfdpc.h (包含 Wdf.h)
程式庫	Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)