WdfCollectionAdd 函数 (wdfcollection.h)

  • 项目

[适用于 KMDF 和 UMDF]

WdfCollectionAdd 方法将指定的框架对象添加到对象集合。

语法

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

参数

[in] Collection

集合对象的句柄。

[in] Object

将添加到集合的框架对象的句柄。

返回值

如果操作成功，WdfCollectionAdd 将返回STATUS_SUCCESS。 否则，此方法可能会返回以下值之一：

返回代码 说明
STATUS_UNSUCCESSFUL
 无法将指定的 对象添加到指定的集合。
 

此方法还可能返回其他 NTSTATUS 值。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

WdfCollectionAdd 方法将指定的 对象追加到集合包含的对象集的末尾。 当 WdfCollectionAdd 将对象添加到集合时，它会递增对象的引用计数。 驱动程序可以调用 WdfCollectionRemove 或 WdfCollectionRemoveItem 来删除对象并减小其引用计数。

有关对象集合的详细信息，请参阅 框架对象集合。

示例

下面的代码示例创建一个集合对象，然后将一组驱动程序创建的请求对象添加到该集合。

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;
    }
}

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.0
最低 UMDF 版本 2.0
标头 wdfcollection.h (包括 Wdf.h)
Library Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL <= DISPATCH_LEVEL
DDI 符合性规则 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另请参阅

WdfCollectionCreate

WdfCollectionRemove

WdfCollectionRemoveItem