Función WdfCollectionAdd (wdfcollection.h)

  • Artículo

[Se aplica a KMDF y UMDF]

El método WdfCollectionAdd agrega un objeto de marco especificado a una colección de objetos.

Sintaxis

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

Parámetros

[in] Collection

Identificador de un objeto de colección.

[in] Object

Identificador del objeto framework que se agregará a la colección.

Valor devuelto

WdfCollectionAdd devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método podría devolver uno de los siguientes valores:

Código devuelto Descripción
STATUS_UNSUCCESSFUL
 No se pudo agregar el objeto especificado a la colección especificada.
 

Este método también podría devolver otros valores NTSTATUS.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Comentarios

El método WdfCollectionAdd anexa el objeto especificado al final del conjunto de objetos que contiene la colección. Cuando WdfCollectionAdd agrega un objeto a una colección, incrementa el recuento de referencias del objeto. El controlador puede llamar a WdfCollectionRemove o WdfCollectionRemoveItem para quitar el objeto y disminuir su recuento de referencias.

Para obtener más información sobre las colecciones de objetos, vea Colecciones de objetos de marco.

Ejemplos

En el ejemplo de código siguiente se crea un objeto de colección y, a continuación, se agrega un conjunto de objetos de solicitud creados por el controlador a la colección.

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

Requisitos

Requisito Value
Plataforma de destino Universal
Versión mínima de KMDF 1.0
Versión mínima de UMDF 2.0
Encabezado wdfcollection.h (incluya Wdf.h)
Library Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL <= DISPATCH_LEVEL
Reglas de cumplimiento de DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Consulte también

WdfCollectionCreate

WdfCollectionRemove

WdfCollectionRemoveItem