Función WdfCollectionAdd (wdfcollection.h)

[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 de marco 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 puede devolver otros valores de NTSTATUS.

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

Observaciones

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 Framework Object Collections.

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 controladores 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	Valor
de la plataforma de destino de	Universal
versión mínima de KMDF	1.0
versión mínima de UMDF	2.0
encabezado de	wdfcollection.h (incluya Wdf.h)
biblioteca de	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