Функция WdfCollectionAdd (wdfcollection.h)

Статья
02/26/2024

[Применимо к KMDF и UMDF]

Метод WdfCollectionAdd добавляет указанный объект платформы в коллекцию объектов .

Синтаксис

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

Параметры

[in] Collection

Дескриптор объекта коллекции.

[in] Object

Дескриптор объекта платформы, который будет добавлен в коллекцию.

Возвращаемое значение

WdfCollectionAdd возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:

Код возврата	Описание
STATUS_UNSUCCESSFUL	Не удалось добавить указанный объект в указанную коллекцию.

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Метод 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)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

См. также раздел

WdfCollectionCreate

WdfCollectionRemove

WdfCollectionRemoveItem