WdfChildListAddOrUpdateChildDescriptionAsPresent function

Description

[Applies to KMDF only]

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

Parameters

ChildList [in]

A handle to a framework child list object.

IdentificationDescription [in]

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

AddressDescription [in, optional]

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:

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:

1. Call WdfChildListBeginScan to prepare the child list for updating.
2. Call WdfChildListAddOrUpdateChildDescriptionAsPresent multiple times to add or update the child descriptions for all of the parent device's children.
3. 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);

See also

EvtChildListCreateDevice

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT

WdfChildListBeginScan

WdfChildListEndScan

WdfDeviceCreate

WdfFdoGetDefaultChildList