PCW_REGISTRATION_INFORMATION 구조체(wdm.h)

아티클
03/05/2024

PCW_REGISTRATION_INFORMATION 구조체는 공급자 및 카운터 세트에 대한 세부 정보를 제공합니다. 대부분의 개발자는 이 구조를 직접 사용하는 대신 CTRPP에서 생성된 RegisterXxx 또는 InitRegistrationInformationXxx 함수를 사용합니다.

구문

typedef struct _PCW_REGISTRATION_INFORMATION {
  ULONG                   Version;
  PCUNICODE_STRING        Name;
  ULONG                   CounterCount;
  PPCW_COUNTER_DESCRIPTOR Counters;
  PPCW_CALLBACK           Callback;
  PVOID                   CallbackContext;
  PCW_REGISTRATION_FLAGS  Flags;
} PCW_REGISTRATION_INFORMATION, *PPCW_REGISTRATION_INFORMATION;

멤버

Version

공급자에 필요한 PCW(Windows용 성능 카운터) 버전을 지정하는 숫자 값입니다.

10.0.19645(NTDDI_VERSION < NTDDI_VERSION_MN) Version 이전에 Windows에서 실행하는 경우 필드를 PCW_VERSION_1(0x100)로 설정해야 합니다. Windows 10.0.19645 이상(NTDDI_VERSION >= NTDDI_VERSION_MN)에서 실행하는 경우 PCW_VERSION_1(0x100) 또는 PCW_VERSION_2(0x200)로 설정할 수 있습니다. 필드가 Version 인식할 수 없는 값으로 설정된 경우 는 PcwRegister STATUS_INVALID_PARAMETER_2 반환합니다.

CTRPP에서 생성된 RegisterXxx 또는 InitRegistrationInformationXxx 함수 Version 를 사용하는 경우 필드는 의 컴파일 시간 값NTDDI_VERSION에 따라 다음 값 중 하나에 해당하는 로 설정PCW_CURRENT_VERSION됩니다.

조건	PCW_CURRENT_VERSION 값
`NTDDI_VERSION < NTDDI_WIN10_FE`	PCW_VERSION_1(0x0100)
`NTDDI_VERSION >= NTDDI_WIN10_FE`	PCW_VERSION_2(0x0200)

코드가 를 NTDDI_VERSION >= NTDDI_WIN10_FE 사용하여 빌드되지만 이전 버전의 Windows에서 실행해야 하는 경우 PcwRegister 설명서에 설명된 대로 를 설정 Version = PCW_VERSION_1 해야 합니다.

Name

등록할 카운터 세트의 이름을 포함하는 문자열에 대한 포인터입니다. 이 문자열은 NULL이거나 비어 있지 않아야 합니다.

카운터셋 이름 비교는 대/소문자를 구분하지 않습니다. 두 개의 카운터 세트 등록에서 동일한 카운터 세트 이름을 사용하는 경우 소비자는 두 등록에서 데이터를 수집합니다.

CounterCount

매개 변수에 제공된 설명자의 수입니다 Counters .

Counters

이 카운터 세트의 카운터에 대한 설명자의 배열입니다. 설명자의 정보는 또는 PcwAddInstance에 대한 호출에서 제공하는 데이터 블록에서 카운터 값을 추출할 PcwCreateInstance 때 사용됩니다.

Callback

이 카운터 세트와 관련된 이벤트에 대해 공급자에게 알려 주는 선택적 PCW_CALLBACK 콜백 함수에 대한 포인터입니다. 콜백이 필요하지 않은 경우(즉, 카운터 세트 인스턴스가 및 PcwCloseInstance를 통해 PcwCreateInstance 관리되는 경우) 이 필드는 NULL일 수 있습니다.

CallbackContext

호출될 때마다 공급자 정의 PCW_CALLBACK 콜백 함수에 전달되는 포인터 값입니다.

Flags

Flags 필드는 에만 사용할 수 있습니다NTDDI_VERSION >= NTDDI_WIN10_MN.

Flags 필드가 보다 PCW_VERSION_2작으면 필드가 Version 무시됩니다.

Flags 필드는 의 특수 동작을 PcwRegister사용하도록 설정합니다. 하나 이상의 PCW_REGISTRATION_FLAGS 값 조합으로 설정합니다.

PCW_REGISTRATION_FLAGS	의미
PcwRegistrationNone(0x0)	기본값(특별한 동작은 필요하지 않음).
PcwRegistrationSiloNeutral(0x1)	이 등록이 모든 서버 사일로의 소비자에게 표시되어야 임을 나타냅니다. 기본적으로 등록은 등록을 만들 때 활성화된 서버 사일로의 소비자에게만 표시됩니다(즉, 호출되었을 때 `PcwRegister` 스레드에 연결된 등록).

설명

PcwRegister 함수는 이 구조체에 Info 대한 포인터인 매개 변수를 사용합니다.

CTRPP에서 생성된 InitRegistrationInformationXxx 함수

대부분의 개발자는 PCW_REGISTRATION_INFORMATION 직접 사용할 필요가 없습니다. 대신 CTRPP 도구를 사용하여 매니페스트를 컴파일하고 CTRPP 생성 헤더에서 RegisterXxx 또는 InitRegistrationInformationXxx 함수를 사용합니다. 생성된 Register 함수는 InitRegistrationInformation을 호출한 다음 를 호출 PcwRegister 합니다(자세한 내용은 PcwRegister 참조). 생성된 InitRegistrationInformation 함수는 다음과 같습니다.

EXTERN_C FORCEINLINE VOID
InitRegistrationInformationMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext,
    __out PCW_REGISTRATION_INFORMATION* RegInfo
    )
{
    static const UNICODE_STRING Name = RTL_CONSTANT_STRING(L"My Counterset Name");
    static const PCW_COUNTER_DESCRIPTOR Descriptors[] = {
        { 0, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData1), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1)},
        { 1, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData2), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2)},
    };

#if CTRPP_VERIFY_COUNTER_SIZES

    //
    // Verify that structure member size matches manifest counter size.
    //

    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1) == sizeof(ULONGLONG));
    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2) == sizeof(ULONG));

#endif // CTRPP_VERIFY_COUNTER_SIZES

    PAGED_CODE();

    RtlZeroMemory(RegInfo, sizeof(*RegInfo));
    RegInfo->Version = PCW_CURRENT_VERSION;
    RegInfo->Name = &Name;
    RegInfo->CounterCount = RTL_NUMBER_OF(Descriptors);
    RegInfo->Counters = (PCW_COUNTER_DESCRIPTOR*)Descriptors;
    RegInfo->Callback = Callback;
    RegInfo->CallbackContext = CallbackContext;
}

CTRPP에서 생성된 InitRegistrationInformation 함수의 이름은 PrefixInitRegistrationInformationCounterset입니다. 접두 사는 일반적으로 비어 있지만 매개 변수가 -prefix CTRPP 명령줄에서 사용된 경우 있을 수 있습니다. 카운터 집합 은 매니페스트에 지정된 카운터 세트의 이름입니다. 생성된 InitRegistrationInformation 함수는 함수 매개 변수 및 매니페스트의 값을 사용하여 제공된 PCW_REGISTRATION_INFORMATION 구조를 초기화합니다.

CTRPP에서 생성된 InitRegistrationInformation 함수는 필요에 따라 구조체 멤버의 크기가 매니페스트에 선언된 크기와 일치하는지 확인할 수 있습니다. 기본적으로 는 CTRPP_VERIFY_COUNTER_SIZES 0으로 설정되며 이 검사 사용하지 않도록 설정됩니다. CTRPP 생성 헤더를 포함하기 전에 이 검사 #define CTRPP_VERIFY_COUNTER_SIZES 1 사용하도록 설정합니다. 검사 사용하도록 설정된 경우 크기 불일치는 C_ASSERT 조건의 실패로 인해 컴파일 오류를 트리거합니다.