WdfWorkItemCreate 함수(wdfworkitem.h)

  • 아티클

[KMDF 및 UMDF에 적용]

WdfWorkItemCreate 메서드는 프레임워크 작업 항목 개체를 만듭니다. 이 개체는 이후에 시스템의 작업 항목 큐에 추가할 수 있습니다.

구문

NTSTATUS WdfWorkItemCreate(
  [in]  PWDF_WORKITEM_CONFIG   Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFWORKITEM            *WorkItem
);

매개 변수

[in] Config

WDF_WORKITEM_CONFIG_INIT 호출하여 드라이버가 이미 초기화해야 하는 호출자가 할당한 WDF_WORKITEM_CONFIG구조체에 대한 포인터입니다.

[in] Attributes

작업 항목 개체의 특성을 지정하는 호출자가 할당한 WDF_OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다.

[out] WorkItem

새 작업 항목 개체에 대한 핸들을 수신하는 변수에 대한 포인터입니다.

반환 값

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

반환 코드 설명
STATUS_INVALID_PARAMETER
 잘못된 매개 변수가 제공되었습니다.
STATUS_INVALID_DEVICE_REQUEST
 작업 항목 개체의 부모는 디바이스 개체 또는 디바이스 개체의 상위 항목이 아닙니다.
STATUS_INSUFFICIENT_RESOURCES
 작업 항목 개체를 만들기 위한 시스템 리소스가 부족했습니다.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL
 Config 매개 변수가 가리키는 WDF_WORKITEM_CONFIG 구조체의 AutomaticSerialization 멤버는 TRUE이지만 부모 개체의 실행 수준은 WdfExecutionLevelPassive가 아닙니다.
STATUS_WDF_PARENT_NOT_SPECIFIED
 Attributes 매개 변수가 NULL이거나 Attributes가 지정한WDF_OBJECT_ATTRIBUTES 구조체의 ParentObject 멤버가 NULL입니다.

설명

드라이버는 WdfWorkItemCreate 를 호출하여 작업 항목을 만든 후 일반적으로 항목별 정보를 작업 항목 개체의 컨텍스트 메모리에 저장합니다. 작업 항목의 작업을 수행하는 드라이버의 EvtWorkItem 콜백 함수는 이 정보에 액세스하여 수행해야 하는 작업을 결정할 수 있습니다. (컨텍스트 메모리에 정보를 저장하는 방법에 대한 자세한 내용은 Framework 개체 컨텍스트 공간을 참조하세요.)

작업 항목 정보를 저장한 후 드라이버는 WdfWorkItemEnqueue 를 호출하여 작업 항목을 시스템의 작업 항목 큐에 추가해야 합니다. 시스템 작업자 스레드를 사용할 수 있게 되면 스레드는 큐에서 작업 항목을 제거하고 EvtWorkItem 콜백 함수를 호출합니다.

드라이버가 작업 항목 개체를 만들 때 WDF_OBJECT_ATTRIBUTES 구조체의 ParentObject 멤버에서 작업 항목 개체에 대한 부모 개체를 지정해야 합니다. 부모 개체는 프레임워크 디바이스 개체이거나 부모 체인이 프레임워크 디바이스 개체로 이어지는 개체여야 합니다. 프레임워크는 디바이스 개체를 삭제할 때 작업 항목 개체를 삭제합니다.

이전에 작업 항목 개체를 삭제하기 위해 드라이버는 프레임워크 작업 항목 사용에 설명된 대로 WdfObjectDelete를 호출할 수 있습니다.

드라이버는 WdfWorkItemGetParentObject를 호출하여 작업 항목의 부모 개체를 검색할 수 있습니다.

드라이버가 작업 항목 개체 에 대해 EvtCleanupCallback 또는 EvtDestroyCallback 콜백 함수를 제공하는 경우 프레임워크는 IRQL = PASSIVE_LEVEL 이러한 콜백 함수를 호출합니다.

작업 항목에 대한 자세한 내용은 프레임워크 작업 항목 사용을 참조하세요.

예제

다음 코드 예제에서는 WDF_OBJECT_ATTRIBUTES 구조를 초기화하고 , WDF_WORKITEM_CONFIG 구조를 초기화하고, WdfWorkItemCreate를 호출합니다.

NTSTATUS  status = STATUS_SUCCESS;
PWORKER_ITEM_CONTEXT  context;
WDF_OBJECT_ATTRIBUTES  attributes;
WDF_WORKITEM_CONFIG  workitemConfig;
WDFWORKITEM  hWorkItem;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                       &attributes,
                                       WORKER_ITEM_CONTEXT
                                       );
attributes.ParentObject = FdoData->WdfDevice;

WDF_WORKITEM_CONFIG_INIT(
                         &workitemConfig,
                         CallbackFunction
                         );

status = WdfWorkItemCreate(
                            &workitemConfig,
                            &attributes,
                            &hWorkItem
                            );
if (!NT_SUCCESS(status)) {
    return status;
}

요구 사항

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

추가 정보

WdfWorkItemEnqueue