WdfCollectionCreate function (wdfcollection.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfCollectionCreate method creates a framework collection object.

Syntax

NTSTATUS WdfCollectionCreate(
  [in, optional] PWDF_OBJECT_ATTRIBUTES CollectionAttributes,
  [out]          WDFCOLLECTION          *Collection
);

Parameters

[in, optional] CollectionAttributes

A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that contains attributes for the new collection object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

[out] Collection

A pointer to a location that receives a handle to the new collection object.

Return value

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

Return code	Description
STATUS_INVALID_PARAMETER	The caller supplied an invalid parameter value.
STATUS_INSUFFICIENT_RESOURCES	A collection object could not be allocated.

This method might also return other NTSTATUS values.

Remarks

After calling WdfCollectionCreate to create a framework collection object, a driver can call WdfCollectionAdd to add objects to the collection.

By default, the new collection object's parent is the framework driver object that the WdfDriverCreate method created. You can use the ParentObject member of the WDF_OBJECT_ATTRIBUTES structure to specify a different parent. The framework deletes the collection object when it deletes the parent object. If your driver does not change the default parent, the driver should delete the collection object when it has finished using the object; otherwise, the object will remain until the I/O manager unloads your driver.

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

Examples

For a code example that uses WdfCollectionCreate, see WdfCollectionAdd.

Requirements

Requirement	Value
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(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)