WDF_OBJECT_ATTRIBUTES 구조체(wdfobject.h)

아티클
02/29/2024

[KMDF 및 UMDF에 적용]

WDF_OBJECT_ATTRIBUTES 구조체는 프레임워크 개체와 연결할 수 있는 특성을 설명합니다.

구문

typedef struct _WDF_OBJECT_ATTRIBUTES {
  ULONG                          Size;
  PFN_WDF_OBJECT_CONTEXT_CLEANUP EvtCleanupCallback;
  PFN_WDF_OBJECT_CONTEXT_DESTROY EvtDestroyCallback;
  WDF_EXECUTION_LEVEL            ExecutionLevel;
  WDF_SYNCHRONIZATION_SCOPE      SynchronizationScope;
  WDFOBJECT                      ParentObject;
  size_t                         ContextSizeOverride;
  PCWDF_OBJECT_CONTEXT_TYPE_INFO ContextTypeInfo;
} WDF_OBJECT_ATTRIBUTES, *PWDF_OBJECT_ATTRIBUTES;

멤버

Size

이 구조체의 크기(바이트)입니다.

EvtCleanupCallback

드라이버의 EvtCleanupCallback 콜백 함수 또는 NULL에 대한 포인터입니다.

EvtDestroyCallback

드라이버의 EvtDestroyCallback 콜백 함수 또는 NULL에 대한 포인터입니다.

ExecutionLevel

프레임워크가 개체의 이벤트 콜백 함수를 호출할 최대 IRQL을 지정하는 WDF_EXECUTION_LEVEL 형식의 값입니다. 드라이버가 ExecutionLevel 값을 지정할 수 있는 프레임워크 개체 목록은 WDF_EXECUTION_LEVEL 참조하세요.

SynchronizationScope

프레임워크가 개체의 이벤트 콜백 함수 실행을 동기화하는 방법을 지정하는 WDF_SYNCHRONIZATION_SCOPE 형식의 값입니다. 드라이버가 SynchronizationScope 값을 지정할 수 있는 프레임워크 개체 목록은 WDF_SYNCHRONIZATION_SCOPE 참조하세요.

ParentObject

개체의 부모 개체에 대한 핸들이거나, 개체에 드라이버 지정 부모가 없는 경우 NULL 입니다.

드라이버 지정 부모를 허용하는 개체를 보여 주는 테이블은 Framework 개체 요약 을 참조하세요. 표에는 각 개체의 기본 부모도 표시됩니다.

ContextSizeOverride

0이 아닌 경우 이 값은 ContextTypeInfo 멤버가 참조하는 WDF_OBJECT_CONTEXT_TYPE_INFO 구조체의 ContextSize 멤버를 재정의합니다. 이 값은 선택 사항이며 0일 수 있습니다. 값이 0이 아니면 WDF_OBJECT_CONTEXT_TYPE_INFO 구조체의 ContextSize 멤버에 대해 지정된 값보다 큰 크기(바이트)를 지정해야 합니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

ContextTypeInfo

WDF_OBJECT_CONTEXT_TYPE_INFO 구조체에 대한 포인터입니다. WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE 매크로는 이 포인터를 설정합니다.

설명

WDF_OBJECT_ATTRIBUTES 구조체는 프레임워크 개체를 만드는 여러 메서드에 대한 입력 인수로 사용됩니다.

WDF_OBJECT_ATTRIBUTES 구조를 초기화하려면 드라이버가 WDF_OBJECT_ATTRIBUTES_INIT 호출해야 합니다.

또한 개체에 대한 개체별 컨텍스트 정보를 정의하는 경우 WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE 매크로를 사용해야 합니다.

또는 WDF_OBJECT_ATTRIBUTES_INIT 및 WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE 매크로 대신 WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE 매크로를 사용할 수 있습니다.

이러한 매크로 사용에 대한 자세한 내용은 프레임워크 개체 컨텍스트 공간을 참조하세요.

변수 길이가 있는 개체 컨텍스트 공간을 만들려면 WDF_OBJECT_ATTRIBUTES ContextSizeOverride 멤버를 사용합니다. 예를 들어 다음과 같이 배열을 포함하는 컨텍스트 공간 구조를 정의할 수 있습니다.

typedef struct _MY_REQUEST_CONTEXT {
  ULONG  ByteCount;
  BYTE  Bytes[1];
} MY_REQUEST_CONTEXT, *PMY_REQUEST_CONTEXT;

WDF_DECLARE_CONTEXT_TYPE(MY_REQUEST_CONTEXT);

드라이버는 컨텍스트 공간 구조를 사용하는 개체를 만들 때 ContextSizeOverride 멤버를 사용하여 각 개별 개체에 필요한 컨텍스트 크기를 지정할 수 있습니다. 예를 들어 드라이버는 이전 예제의 배열에 필요한 바이트 수를 계산한 다음 ContextSizeOverride 를 사용하여 다음과 같이 추가 바이트를 지정할 수 있습니다.

WDF_OBJECT_ATTRIBUTES MyRequestObjectAttributes;
PMY_REQUEST_CONTEXT pMyContext;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &MyRequestObjectAttributes,
                                        MY_REQUEST_CONTEXT
                                        );
MyRequestObjectAttributes.ContextSizeOverride =
                          sizeof(MY_REQUEST_CONTEXT) + Num_Extra_Bytes - 1;

그런 다음 드라이버는 사용자 지정된 컨텍스트 크기로 개체를 만들 수 있습니다.

status = WdfRequestCreate(
                          &MyRequestObjectAttributes,
                          ioTarget,
                          &newRequest
                          );

프레임워크 개체 계층 구조에 대한 정리 규칙에 대한 자세한 내용은 Framework 개체 수명 주기를 참조하세요.