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 호출하여 개체를 제거하고 참조 수를 감소할 수 있습니다.

개체 컬렉션에 대한 자세한 내용은 Framework 개체 컬렉션참조하세요.

예제

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

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