WdfChildListAddOrUpdateChildDescriptionAsPresent function (wdfchildlist.h)
[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 |
---|---|
|
An input parameter was invalid. |
|
The size of the identification description or address description was incorrect. |
|
A child with the supplied identification description already exists. In this case, the framework copies the supplied address description to the existing child. |
|
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.
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) |
See also
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER