WdfChildListAddOrUpdateChildDescriptionAsPresent, fonction (wdfchildlist.h)

Article
02/07/2025

[S’applique uniquement à KMDF]

La méthode WdfChildListAddOrUpdateChildDescriptionAsPresentAsPres ent ajoute une nouvelle description enfant à une liste d’enfants ou met à jour une description enfant existante.

Syntaxe

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

Paramètres

[in] ChildList

Handle d’un objet de liste enfant framework.

[in] IdentificationDescription

Pointeur vers une structure WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER qui identifie une description d’identification enfant.

[in, optional] AddressDescription

Pointeur vers une structure WDF_CHILD_ADDRESS_DESCRIPTION_HEADER qui identifie une description d’adresse de enfant. Si une description d’adresse n’est pas nécessaire, ce paramètre peut être NULL.

Valeur de retour

WdfChildListAddOrUpdateChildDescriptionAsPresent retourne STATUS_SUCCESS, ou une autre valeur d’état typée NTSTATUS pour laquelle NT_SUCCESS(status) est égal à TRUE, si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Retourner le code	Description
STATUS_INVALID_PARAMETER	Un paramètre d’entrée n’était pas valide.
STATUS_INVALID_DEVICE_REQUEST	La taille de la description d’identification ou de la description de l’adresse était incorrecte.
STATUS_OBJECT_NAME_EXISTS	Un enfant avec la description d’identification fournie existe déjà. Dans ce cas, l’infrastructure copie la description de l’adresse fournie sur l’enfant existant.
STATUS_INSUFFICIENT_RESOURCES	Une description enfant peut être allouée.

Cette méthode peut également retourner d’autres valeurs NTSTATUS .

Une vérification des bogues système se produit si le pilote fournit un handle d’objet non valide.

Remarques

La méthode WdfChildListAddOrUpdateChildDescriptionAsPresent recherche la liste enfant spécifiée pour un enfant qui correspond à la description d’identification fournie. Si une correspondance est trouvée, l’infrastructure met à jour la description de l’adresse de l’enfant, le cas échéant, et retourne STATUS_OBJECT_NAME_EXISTS. Si aucune correspondance n’est trouvée, l’infrastructure crée un enfant à l’aide des descriptions d’identification et d’adresse fournies.

Un pilote peut appeler WdfChildListAddOrUpdateChildDescriptionAsPresent pour ajouter ou mettre à jour une seule description enfant. L’infrastructure met immédiatement à jour la liste enfant et informe le gestionnaire Plug-and-Play (PnP) que des modifications ont été apportées.

Vous pouvez également effectuer les opérations suivantes :

Appelez WdfChildListBeginScan pour préparer la liste enfant pour la mise à jour.
Appelez WdfChildListAddOrUpdateChildDescriptionAsPresent plusieurs fois pour ajouter ou mettre à jour les descriptions enfants de tous les enfants de l’appareil parent.
Appelez WdfChildListEndScan pour traiter les modifications apportées à la liste enfant.

Si le pilote utilise cette autre procédure, l’infrastructure attend que le pilote appelle WdfChildListEndScan avant de mettre à jour la liste enfant et d’informer le gestionnaire PnP que les modifications ont été apportées. Lorsque votre pilote appelle WdfChildListBeginScan, l’infrastructure marque tous les appareils précédemment signalés comme n’étant plus présents. Par conséquent, le pilote doit appeler WdfChildListAddOrUpdateChildDescriptionAsPresent pour tous les enfants, pas seulement les enfants nouvellement découverts.

À un moment donné après qu’un pilote appelle WdfChildListAddOrUpdateChildDescriptionAsPresent, l’infrastructure appelle la fonction de rappel EvtChildListCreateDevice afin que le pilote puisse créer un objet d’appareil en appelant WdfDeviceCreate.

Pour plus d’informations sur les listes enfants, consultez d’énumération dynamique .

Exemples

L’exemple de code suivant est basé sur le code que contient l’exemple de kmdf_fx2. L’exemple ajoute des descriptions enfants à la liste enfant par défaut d’un appareil. Il récupère les paramètres de commutateur que le pilote a précédemment stockés dans l’espace contextuel d’un objet d’appareil, puis appelle WdfChildListAddOrUpdateChildDescriptionAsPresent pour chaque commutateur défini.

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

Exigences

Exigence	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
d’en-tête	wdfchildlist.h (include Wdf.h)
bibliothèque	Wdf01000.sys (voir Versioning de la bibliothèque Framework.)
IRQL	<= DISPATCH_LEVEL
règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)