WdfCollectionAdd 函式 (wdfcollection.h)

  • 發行項

[適用於 KMDF 和 UMDF]

WdfCollectionAdd 方法會將指定的架構物件新增至物件集合。

語法

NTSTATUS WdfCollectionAdd(
  [in] WDFCOLLECTION Collection,
  [in] WDFOBJECT     Object
);

參數

[in] Collection

集合物件的句柄。

[in] Object

將加入至集合之架構物件的句柄。

傳回值

如果作業成功，WdfCollectionAdd 會傳回STATUS_SUCCESS。 否則，此方法可能會傳回下列其中一個值：

傳回碼 Description
STATUS_UNSUCCESSFUL
 指定的物件無法加入至指定的集合。
 

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

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

備註

WdfCollectionAdd 方法會將指定的物件附加至集合所包含之物件集的結尾。 當 WdfCollectionAdd 將物件新增至集合時，它會遞增對象的參考計數。 您的驅動程式可以呼叫 WdfCollectionRemove 或 WdfCollectionRemoveItem 來移除物件，並遞減其參考計數。

如需物件集合的詳細資訊，請參閱 Framework 物件集合。

範例

下列程式代碼範例會建立集合物件，然後將一組驅動程式建立的要求物件新增至集合。

WDF_OBJECT_ATTRIBUTES  attributes;
NTSTATUS  status;
WDFCOLLECTION  hCollection = NULL;
WDFREQUEST  subRequest = NULL;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = Request;
status = WdfCollectionCreate(
                             &attributes,
                             &hCollection
                             );
if (!NT_SUCCESS(status)) {
    goto Exit;
}

for (i = 0; i < numSubRequests; i++) {
    WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
    WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                           &attributes,
                                           SUB_REQUEST_CONTEXT
                                           );
    status = WdfRequestCreate(
                              &attributes,
                              WdfUsbTargetDeviceGetIoTarget(deviceContext->WdfUsbTargetDevice),
                              &subRequest
                              );
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    status = WdfCollectionAdd(
                              hCollection,
                              subRequest
                              );
    if (!NT_SUCCESS(status)) {
        WdfObjectDelete(subRequest);
        goto Exit;
    }
}

規格需求

需求 值
目標平台 Universal
最小 KMDF 版本 1.0
最低UMDF版本 2.0
標頭 wdfcollection.h (包含 Wdf.h)
程式庫 Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL <= DISPATCH_LEVEL
DDI 合規性規則 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另請參閱

WdfCollectionCreate

WdfCollectionRemove

WdfCollectionRemoveItem