Função WdfCollectionAdd (wdfcollection.h)

Artigo
02/07/2025

[Aplica-se a KMDF e UMDF]

O método WdfCollectionAdd adiciona um objeto de estrutura especificado a uma coleção de objetos.

Sintaxe

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

Parâmetros

[in] Collection

Um identificador para um objeto de coleção.

[in] Object

Um identificador para o objeto de estrutura que será adicionado à coleção.

Valor de retorno

WdfCollectionAdd retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método poderá retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_UNSUCCESSFUL	O objeto especificado não pôde ser adicionado à coleção especificada.

Esse método também pode retornar outros valores NTSTATUS .

Uma verificação de bug ocorre se o driver fornece um identificador de objeto inválido.

Observações

O método WdfCollectionAdd acrescenta o objeto especificado ao final do conjunto de objetos que a coleção contém. Quando WdfCollectionAdd adiciona um objeto a uma coleção, ele incrementa a contagem de referência do objeto. O driver pode chamar WdfCollectionRemove ou WdfCollectionRemoveItem para remover o objeto e diminuir sua contagem de referência.

Para obter mais informações sobre coleções de objetos, consulte Coleções de Objetos da Estrutura.

Exemplos

O exemplo de código a seguir cria um objeto de coleção e adiciona um conjunto de objetos de solicitação criados pelo driver à coleção.

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

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
versão mínima do KMDF	1.0
versão mínima do UMDF	2.0
cabeçalho	wdfcollection.h (inclua Wdf.h)
biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Consulte também

WdfCollectionCreate

WdfCollectionRemove

WdfCollectionRemoveItem

Compartilhar via