WdfDpcCreate 函式（wdfdpc.h）

發行項
03/22/2025

[僅適用於 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	指定了無效的參數。
資源不足狀態	無法配置 DPC 物件。
STATUS_WDF_PARENT_NOT_SPECIFIED	WDF_OBJECT_ATTRIBUTES 結構中未指定父物件。
STATUS_INVALID_DEVICE_REQUEST	ParentObjectWDF_OBJECT_ATTRIBUTES 結構的成員不會參考架構裝置物件或父系鏈結導致架構裝置物件的物件。
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	WDF_DPC_CONFIG 結構的自動串行化成員會設定為 true ，但父物件的執行層級會設定為 WdfExecutionLevelPassive。

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

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

備註

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

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

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

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