WdfChildListCreate 函式 (wdfchildlist.h)

  • 發行項

[僅適用於 KMDF]

WdfChildListCreate 方法會為指定的父裝置建立子清單。

語法

NTSTATUS WdfChildListCreate(
  [in]           WDFDEVICE              Device,
  [in]           PWDF_CHILD_LIST_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES ChildListAttributes,
  [out]          WDFCHILDLIST           *ChildList
);

參數

[in] Device

表示父裝置之架構裝置物件的句柄。

[in] Config

WDF_CHILD_LIST_CONFIG 結構的指標，其中包含子清單的驅動程式提供的組態資訊。

[in, optional] ChildListAttributes

WDF_OBJECT_ATTRIBUTES 結構的指標，其中包含架構子清單對象的驅動程式提供物件屬性。 (結構的 ParentObject 成員必須是 NULL.)

[out] ChildList

呼叫端配置位置的指標，可接收架構子清單物件的句柄。

傳回值

如果作業成功，WdfChildListCreate 會傳回STATUS_SUCCESS或另一個狀態值，NT_SUCCESS (狀態) 等於 TRUE。 否則，此方法可能會傳回下列其中一個值：

傳回碼 Description
STATUS_INVALID_PARAMETER
 輸入參數無效。
STATUS_INSUFFICIENT_RESOURCES
 無法配置物件。
 

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

如果驅動程式提供無效的物件句柄，就會發生系統錯誤檢查。

備註

架構會為每個架構裝置物件建立預設子清單，此物件代表 FDO) (功能性裝置物件。 若要使用預設子清單，驅動程式會呼叫 WdfFdoGetDefaultChildList。 如果您的驅動程式需要其他子清單，它可以呼叫 WdfChildListCreate 來建立它們。

每個子清單物件的父代都是裝置的架構裝置物件。 驅動程式無法變更這個父代， 而 ParentObject 成員或 WDF_OBJECT_ATTRIBUTES 結構必須是 NULL。

您的驅動程式無法刪除 WdfChildListCreate 所建立的子清單物件。 架構會在適當的時間刪除物件。

如需子清單的詳細資訊，請參閱 動態列舉。

範例

下列程式代碼範例會初始化 WDF_CHILD_LIST_CONFIG 結構，然後呼叫 WdfChildListCreate。

WDF_CHILD_LIST_CONFIG listConfig;

WDF_CHILD_LIST_CONFIG_INIT(
                           &listConfig,
                           sizeof(PDO_IDENTIFICATION_DESCRIPTION),
                           My_EvtDeviceListCreatePdo
                           );

listConfig.AddressDescriptionSize = sizeof(PDO_ADDRESS_DESCRIPTION);

listConfig.EvtChildListScanForChildren = My_EvtChildListScanForChildren;

listConfig.EvtChildListIdentificationDescriptionDuplicate = My_EvtChildListIdentificationDescriptionDuplicate;
listConfig.EvtChildListIdentificationDescriptionCompare = My_EvtChildListIdentificationDescriptionCompare;
listConfig.EvtChildListIdentificationDescriptionCleanup = My_EvtChildListIdentificationDescriptionCleanup;

status = WdfChildListCreate(
                            device,
                            &listConfig,
                            WDF_NO_OBJECT_ATTRIBUTES,
                            &ParentDeviceContext->ChildList
                            );
if (!NT_SUCCESS(status)) {
    return status;
}

規格需求

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

另請參閱

WDF_CHILD_LIST_CONFIG

WDF_CHILD_LIST_CONFIG_INIT

WdfFdoGetDefaultChildList