WdfChildListAddOrUpdateChildDescriptionAsPresent function (wdfchildlist.h)

Article
02/22/2024

[Applies to KMDF only]

The WdfChildListAddOrUpdateChildDescriptionAsPresent method adds a new child description to a list of children or updates an existing child description.

Syntax

NTSTATUS WdfChildListAddOrUpdateChildDescriptionAsPresent(
  [in]           WDFCHILDLIST                                 ChildList,
  [in]           PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription,
  [in, optional] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER        AddressDescription
);

Parameters

[in] ChildList

A handle to a framework child list object.

[in] IdentificationDescription

A pointer to a WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER structure that identifies a child identification description.

[in, optional] AddressDescription

A pointer to a WDF_CHILD_ADDRESS_DESCRIPTION_HEADER structure that identifies a child address description. If an address description is not needed, this parameter can be NULL.

Return value

WdfChildListAddOrUpdateChildDescriptionAsPresent returns STATUS_SUCCESS, or another NTSTATUS-typed status value for which NT_SUCCESS(status) equals TRUE, if the operation succeeds. Otherwise, this method might return one of the following values:

Return code	Description
STATUS_INVALID_PARAMETER	An input parameter was invalid.
STATUS_INVALID_DEVICE_REQUEST	The size of the identification description or address description was incorrect.
STATUS_OBJECT_NAME_EXISTS	A child with the supplied identification description already exists. In this case, the framework copies the supplied address description to the existing child.
STATUS_INSUFFICIENT_RESOURCES	A child description could be allocated.

This method might also return other NTSTATUS values.

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

Remarks

The WdfChildListAddOrUpdateChildDescriptionAsPresent method searches the specified child list for a child that matches the supplied identification description. If a match is found, the framework updates the child's address description, if supplied, and returns STATUS_OBJECT_NAME_EXISTS. If no match is found, the framework creates a new child by using the supplied identification and address descriptions.

A driver can call WdfChildListAddOrUpdateChildDescriptionAsPresent to add or update a single child description. The framework immediately updates the child list and informs the Plug and Play (PnP) manager that changes have been made.

Alternatively, the driver can do the following:

Call WdfChildListBeginScan to prepare the child list for updating.
Call WdfChildListAddOrUpdateChildDescriptionAsPresent multiple times to add or update the child descriptions for all of the parent device's children.
Call WdfChildListEndScan to process changes to the child list.

If the driver uses this alternative procedure, the framework waits until the driver calls WdfChildListEndScan before updating the child list and informing the PnP manager that changes have been made. When your driver calls WdfChildListBeginScan, the framework marks all previously reported devices as no longer being present. Therefore, the driver must call WdfChildListAddOrUpdateChildDescriptionAsPresent for all children, not just newly discovered children.

At some time after a driver calls WdfChildListAddOrUpdateChildDescriptionAsPresent, the framework calls the driver's EvtChildListCreateDevice callback function so that the driver can create a device object by calling WdfDeviceCreate.

For more information about child lists, see Dynamic Enumeration.

Examples

The following code example is based on code that the kmdf_fx2 sample contains. The example adds child descriptions to a device's default child list. It retrieves switch settings that the driver previously stored in a device object's context space and then calls WdfChildListAddOrUpdateChildDescriptionAsPresent for each switch that is set.

PDEVICE_CONTEXT  pDeviceContext;
WDFCHILDLIST  list;
UCHAR  i;
NTSTATUS  status;

pDeviceContext = GetDeviceContext(Device);
list = WdfFdoGetDefaultChildList(Device);

WdfChildListBeginScan(list);
 
for (i = 0; i < RTL_BITS_OF(UCHAR); i++) {
    if (pDeviceContext->CurrentSwitchState & (1<<i)) {
        PDO_IDENTIFICATION_DESCRIPTION description;
        WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                 &description.Header,
                                                 sizeof(description)
                                                 );
        description.SwitchNumber = i; 
 
        status = WdfChildListAddOrUpdateChildDescriptionAsPresent(
                                                 list, 
                                                 &description.Header, 
                                                 NULL
                                                 );
        if (!NT_SUCCESS(status) && (status != STATUS_OBJECT_NAME_EXISTS)) {
            break;
        }
    }
}
WdfChildListEndScan(list);

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Header	wdfchildlist.h (include Wdf.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	<= DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)