WdfChildListAddOrUpdateChildDescriptionAsPresent 函式 (wdfchildlist.h)

發行項
02/26/2024

[僅適用於 KMDF]

WdfChildListAddOrUpdateChildDescriptionAsPresent 方法會將新的子描述新增至子系列表，或更新現有的子描述。

語法

NTSTATUS WdfChildListAddOrUpdateChildDescriptionAsPresent(
  [in]           WDFCHILDLIST                                 ChildList,
  [in]           PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription,
  [in, optional] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER        AddressDescription
);

參數

[in] ChildList

架構子清單物件的句柄。

[in] IdentificationDescription

識別子識別描述之WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER結構的指標。

[in, optional] AddressDescription

識別子位址描述之WDF_CHILD_ADDRESS_DESCRIPTION_HEADER結構的指標。如果不需要位址描述，此參數可以是 NULL。

傳回值

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

傳回碼	Description
STATUS_INVALID_PARAMETER	輸入參數無效。
STATUS_INVALID_DEVICE_REQUEST	標識元描述或位址描述的大小不正確。
STATUS_OBJECT_NAME_EXISTS	具有所提供識別描述的子系已經存在。在此情況下，架構會將提供的位址描述複製到現有的子系。
STATUS_INSUFFICIENT_RESOURCES	可以配置子描述。

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

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

備註

WdfChildListAddOrUpdateChildDescriptionAsPresent 方法會搜尋指定的子清單，尋找符合所提供識別描述的子系。如果找到相符專案，架構會更新子系的位址描述，如果有提供，則會傳回STATUS_OBJECT_NAME_EXISTS。如果找不到相符專案，架構會使用提供的識別和位址描述來建立新的子系。

驅動程式可以呼叫 WdfChildListAddOrUpdateChildDescriptionAsPresent 來新增或更新單一子描述。架構會立即更新子清單，並通知隨插即用 (PnP) 管理員已進行變更。

或者，驅動程式可以執行下列動作：

呼叫 WdfChildListBeginScan 以準備要更新的子清單。
呼叫 WdfChildListAddOrUpdateChildDescriptionAsPresent 多次，以新增或更新所有父裝置子系的子系描述。
呼叫 WdfChildListEndScan 來處理子清單的變更。

如果驅動程式使用此替代程式，架構會等到驅動程式在更新子清單之前呼叫 WdfChildListEndScan ，並通知 PnP 管理員已進行變更。當您的驅動程式呼叫 WdfChildListBeginScan 時，架構會將先前回報的所有裝置標示為不再存在。因此，驅動程式必須為所有子系呼叫 WdfChildListAddOrUpdateChildDescriptionAsPresent ，而不只是新探索到的子系。

在驅動程式呼叫 WdfChildListAddOrUpdateChildDescriptionAsPresent 之後，架構會呼叫驅動程式的 EvtChildListCreateDevice 回呼函式，讓驅動程式可以呼叫 WdfDeviceCreate 來建立裝置物件。

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

範例

下列程式代碼範例是以 kmdf_fx2 範例所包含的程式代碼為基礎。此範例會將子描述新增至裝置的預設子清單。它會擷取驅動程式先前儲存在裝置對象內容空間中的交換器設定，然後針對所設定的每個交換器呼叫 WdfChildListAddOrUpdateChildDescriptionAsPresent 。

PDEVICE_CONTEXT  pDeviceContext;
WDFCHILDLIST  list;
UCHAR  i;
NTSTATUS  status;

pDeviceContext = GetDeviceContext(Device);
list = WdfFdoGetDefaultChildList(Device);

WdfChildListBeginScan(list);
 
for (i = 0; i < RTL_BITS_OF(UCHAR); i++) {
    if (pDeviceContext->CurrentSwitchState & (1<<i)) {
        PDO_IDENTIFICATION_DESCRIPTION description;
        WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                 &description.Header,
                                                 sizeof(description)
                                                 );
        description.SwitchNumber = i; 
 
        status = WdfChildListAddOrUpdateChildDescriptionAsPresent(
                                                 list, 
                                                 &description.Header, 
                                                 NULL
                                                 );
        if (!NT_SUCCESS(status) && (status != STATUS_OBJECT_NAME_EXISTS)) {
            break;
        }
    }
}
WdfChildListEndScan(list);

規格需求

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