WdfCollectionAdd 함수(wdfcollection.h)

[KMDF 및 UMDF에 적용]

WdfCollectionAdd 메서드는 개체 컬렉션에 지정된 프레임워크 개체를 추가합니다.

구문

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

매개 변수

[in] Collection

컬렉션 개체에 대한 핸들입니다.

[in] Object

컬렉션에 추가될 프레임워크 개체에 대한 핸들입니다.

반환 값

WdfCollectionAdd 는 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	설명
STATUS_UNSUCCESSFUL	지정된 개체를 지정된 컬렉션에 추가할 수 없습니다.

 

이 메서드는 다른 NTSTATUS 값을 반환할 수도 있습니다.

드라이버가 잘못된 개체 핸들을 제공하는 경우 버그 검사 발생합니다.

설명

WdfCollectionAdd 메서드는 컬렉션에 포함된 개체 집합의 끝에 지정된 개체를 추가합니다. WdfCollectionAdd가 컬렉션에 개체를 추가하면 개체의 참조 수가 증가합니다. 드라이버는 WdfCollectionRemove 또는 WdfCollectionRemoveItem 을 호출하여 개체를 제거하고 참조 수를 감소할 수 있습니다.

개체 컬렉션에 대한 자세한 내용은 프레임워크 개체 컬렉션을 참조하세요.

예제

다음 코드 예제에서는 컬렉션 개체를 만든 다음 드라이버에서 만든 요청 개체 집합을 컬렉션에 추가합니다.

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

요구 사항

요구 사항	값
대상 플랫폼	유니버설
최소 KMDF 버전	1.0
최소 UMDF 버전	2.0
머리글	wdfcollection.h(Wdf.h 포함)
라이브러리	Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF)
IRQL	<= DISPATCH_LEVEL
DDI 규정 준수 규칙	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

추가 정보

WdfCollectionCreate

WdfCollectionRemove

WdfCollectionRemoveItem