WdfChildListAddOrUpdateChildDescriptionAsPresent, fonction (wdfchildlist.h)

Article
08/08/2023

[S’applique à KMDF uniquement]

La méthode WdfChildListAddOrUpdateChildDescriptionAsPresent 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 pour un objet de liste enfant du 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 enfant. Si aucune description d’adresse n’est nécessaire, ce paramètre peut être NULL.

Valeur retournée

WdfChildListAddOrUpdateChildDescriptionAsPresent retourne STATUS_SUCCESS, ou une autre valeur de status de type 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 :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre d’entrée n’était pas valide.
STATUS_INVALID_DEVICE_REQUEST	La taille de la description de l’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 d’adresse fournie vers l’enfant existant.
STATUS_INSUFFICIENT_RESOURCES	Une description enfant peut être allouée.

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

Un bogue système case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

La méthode WdfChildListAddOrUpdateChildDescriptionAsPresent recherche dans la liste enfant spécifiée 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, si elle est fournie, 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.

Le pilote peut également effectuer les opérations suivantes :

Appelez WdfChildListBeginScan pour préparer la liste enfant à mettre à 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 des modifications ont été apportées. Lorsque votre pilote appelle WdfChildListBeginScan, le framework 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 pour les enfants nouvellement découverts.

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

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

Exemples

L’exemple de code suivant est basé sur le code que contient l’exemple 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);

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfchildlist.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion des versions de la bibliothèque d’infrastructure).)
IRQL	<= DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)