PCW_REGISTRATION_INFORMATION 구조체(wdm.h)
PCW_REGISTRATION_INFORMATION 구조체는 공급자 및 카운터 세트에 대한 세부 정보를 제공합니다. 대부분의 개발자는 이 구조를 직접 사용하는 대신 CTRPP-generated 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) 이전에 Windows에서 실행하는 경우 Version 필드를 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
이 카운터 세트의 카운터에 대한 설명자의 배열입니다. 설명자의 정보는 PcwCreateInstance 또는 PcwAddInstance호출에서 제공하는 데이터 블록에서 카운터 값을 추출할 때 사용됩니다.
Callback
이 카운터 세트와 관련된 이벤트에 대해 공급자에게 알리는 선택적 PCW_CALLBACK 콜백 함수에 대한 포인터입니다. 콜백이 필요하지 않은 경우(즉, 카운터 세트 인스턴스가 PcwCreateInstance 통해 관리되고 PcwCloseInstance경우) 이 필드는 NULL일 수 있습니다.
CallbackContext
호출될 때마다 공급자 정의 PCW_CALLBACK 콜백 함수에 전달되는 포인터 값입니다.
Flags
Flags 필드는 NTDDI_VERSION >= NTDDI_WIN10_MN경우에만 사용할 수 있습니다.
Version 필드가 PCW_VERSION_2미만이면 Flags 필드는 무시됩니다.
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 함수는 접두사InitRegistrationInformationCounterset이름이 지정됩니다.
접두사 일반적으로 비어 있지만 ctrPP 명령줄에서 -prefix 매개 변수를 사용한 경우 있을 수 있습니다.
카운터 세트 매니페스트에 지정된 대로 카운터 세트의 이름입니다. 생성된 InitRegistrationInformation 함수는 제공된 PCW_REGISTRATION_INFORMATION 구조체를 함수 매개 변수 및 매니페스트의 값으로 초기화합니다.
CTRPP에서 생성된 InitRegistrationInformation 함수는 필요에 따라 구조체 멤버의 크기가 매니페스트에 선언된 크기와 일치하는지 확인할 수 있습니다. 기본적으로 CTRPP_VERIFY_COUNTER_SIZES 0으로 설정되어 이 검사를 사용하지 않도록 설정합니다. 이 검사를 사용하도록 설정하려면 CTRPP에서 생성된 헤더를 포함하기 전에 #define CTRPP_VERIFY_COUNTER_SIZES 1. 검사를 사용하도록 설정하면 크기가 일치하지 않으면 C_ASSERT 조건의 실패로 인해 컴파일 오류가 트리거됩니다.
요구 사항
| 요구 | 값 |
|---|---|
| 헤더 | wdm.h(Wdm.h, Ntddk.h 포함) |