WdfCollectionAdd method

[Applies to KMDF and UMDF]

The WdfCollectionAdd method adds a specified framework object to an object collection.

Syntax


NTSTATUS WdfCollectionAdd(
  _In_ WDFCOLLECTION Collection,
  _In_ WDFOBJECT     Object
);

Parameters

Collection [in]

A handle to a collection object.

Object [in]

A handle to the framework object that will be added to the collection.

Return value

WdfCollectionAdd returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:

Return codeDescription
STATUS_UNSUCCESSFUL

The specified object could not be added to the specified collection.

 

This method might also return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

The WdfCollectionAdd method appends the specified object to the end of the set of objects that the collection contains. When WdfCollectionAdd adds an object to a collection, it increments the object's reference count. Your driver can call WdfCollectionRemove or WdfCollectionRemoveItem to remove the object and decrement its reference count.

For more information about object collections, see Framework Object Collections.

Examples

The following code example creates a collection object and then adds a set of driver-created request objects to the collection.


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

Requirements

Target platform

Universal

Minimum KMDF version

1.0

Minimum UMDF version

2.0

Header

Wdfcollection.h (include Wdf.h)

Library

Wdf01000.sys (KMDF);
WUDFx02000.dll (UMDF)

IRQL

<= DISPATCH_LEVEL

DDI compliance rules

DriverCreate, KmdfIrql, KmdfIrql2

See also

WdfCollectionCreate
WdfCollectionRemove
WdfCollectionRemoveItem

 

 

Send comments about this topic to Microsoft

Show: