WdfCollectionAdd, fonction (wdfcollection.h)

  • Article

[S’applique à KMDF et UMDF]

La méthode WdfCollectionAdd ajoute un objet framework spécifié à une collection d’objets.

Syntaxe

NTSTATUS WdfCollectionAdd(
  [in] WDFCOLLECTION Collection,
  [in] WDFOBJECT     Object
);

Paramètres

[in] Collection

Handle d’un objet de collection.

[in] Object

Handle à l’objet framework qui sera ajouté à la collection.

Valeur retournée

WdfCollectionAdd retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour Description
STATUS_UNSUCCESSFUL
 L’objet spécifié n’a pas pu être ajouté à la collection spécifiée.
 

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

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

Remarques

La méthode WdfCollectionAdd ajoute l’objet spécifié à la fin du jeu d’objets que contient la collection. Lorsque WdfCollectionAdd ajoute un objet à une collection, il incrémente le nombre de références de l’objet. Votre pilote peut appeler WdfCollectionRemove ou WdfCollectionRemoveItem pour supprimer l’objet et décrémenter son nombre de références.

Pour plus d’informations sur les collections d’objets, consultez Collections d’objets Framework.

Exemples

L’exemple de code suivant crée un objet de collection, puis ajoute un ensemble d’objets de requête créés par un pilote à la collection.

WDF_OBJECT_ATTRIBUTES  attributes;
NTSTATUS  status;
WDFCOLLECTION  hCollection = NULL;
WDFREQUEST  subRequest = NULL;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = Request;
status = WdfCollectionCreate(
                             &attributes,
                             &hCollection
                             );
if (!NT_SUCCESS(status)) {
    goto Exit;
}

for (i = 0; i < numSubRequests; i++) {
    WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
    WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                           &attributes,
                                           SUB_REQUEST_CONTEXT
                                           );
    status = WdfRequestCreate(
                              &attributes,
                              WdfUsbTargetDeviceGetIoTarget(deviceContext->WdfUsbTargetDevice),
                              &subRequest
                              );
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    status = WdfCollectionAdd(
                              hCollection,
                              subRequest
                              );
    if (!NT_SUCCESS(status)) {
        WdfObjectDelete(subRequest);
        goto Exit;
    }
}

Configuration requise

Condition requise Valeur
Plateforme cible Universal
Version KMDF minimale 1.0
Version UMDF minimale 2.0
En-tête wdfcollection.h (inclure Wdf.h)
Bibliothèque Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL <= DISPATCH_LEVEL
Règles de conformité DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi

WdfCollectionCreate

WdfCollectionRemove

WdfCollectionRemoveItem