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