PcwRegister 함수(wdm.h)

아티클
02/27/2024

함수는 PcwRegister 새 카운터 세트 등록을 만듭니다. 대부분의 개발자는 이 함수를 직접 호출하는 대신 CTRPP에서 생성된 RegisterXxx 함수를 사용합니다.

구문

NTSTATUS PcwRegister(
  [out] PPCW_REGISTRATION             *Registration,
  [in]  PPCW_REGISTRATION_INFORMATION Info
);

매개 변수

[out] Registration

PPCW_REGISTRATION 대한 포인터입니다. 새 등록에 대한 핸들을 받습니다. PcwUnregister를 사용하여 등록을 닫아야 합니다.

[in] Info

등록되는 카운터 세트에 대한 세부 정보를 포함하는 PCW_REGISTRATION_INFORMATION 구조체에 대한 포인터입니다.

반환 값

PcwRegister 는 다음 값 중 하나를 반환합니다.

반환 코드	설명
`STATUS_SUCCESS`	카운터 세트가 성공적으로 등록되었습니다.
`STATUS_INTEGER_OVERFLOW`	이 등록에 의해 노출되는 카운터 수가 지원되는 최대값을 초과합니다.
`STATUS_NO_MEMORY`	카운터에 메모리를 할당하는 데 사용할 수 있는 공간이 부족합니다.
`STATUS_INVALID_PARAMETER_2`	매개 변수에서 `Info` 문제가 발견되었습니다. 몇 가지 가능한 원인은 아래를 참조하세요.

PcwRegister 는 다음과 같은 경우에 반환 STATUS_INVALID_PARAMETER_2 할 수 있습니다.

Info->Name->Length 필드는 0이거나 의 sizeof(WCHAR)배수가 아닙니다.
필드가 Info->Version 이 버전의 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)로 설정할 수 있습니다.
필드에는 Info->Flags 실행 중인 Windows 버전에서 인식할 수 없는 값이 포함됩니다.

설명

공급자는 이 함수를 호출하여 새 카운터 세트 등록을 만듭니다. 호출자가 복사본을 유지할 필요가 없도록 모든 입력 인수가 캡처됩니다.

기본적으로 새 카운터 세트는 등록 시 활성화된 서버 사일로에만 표시됩니다(즉 PcwRegister , 가 호출되면 스레드 PcwRegister 에 연결된 서버 사일로와 새로 만든 등록을 연결). Windows 10.0.19645 이상(NTDDI_VERSION >= NTDDI_VERSION_MN)에서 실행하는 경우 를 로 설정하고 를 로 설정 PCW_REGISTRATION_INFORMATION::FlagsPCW_REGISTRATION_INFORMATION::VersionPCW_VERSION_2PcwRegistrationSiloNeutral하여 모든 서버 사일로에 표시되는 카운터셋 등록을 만들 수 있습니다.

CTRPP에서 생성된 RegisterXxx 함수

대부분의 개발자는 직접 호출 PcwRegister 할 필요가 없습니다. 대신 CTRPP 도구를 사용하여 매니페스트를 컴파일하고 CTRPP 생성 헤더에서 RegisterXxx 함수를 사용합니다. 생성된 함수는 다음과 같습니다.

EXTERN_C FORCEINLINE NTSTATUS
RegisterMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext
    )
{
    PCW_REGISTRATION_INFORMATION RegInfo;

    PAGED_CODE();

    InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

    return PcwRegister(&MyCounterset, &RegInfo);
}

CTRPP에서 생성된 Register 함수의 이름은 접두사레지스터카운터 세트입니다. 접두 사는 일반적으로 비어 있지만 매개 변수가 -prefix CTRPP 명령줄에서 사용된 경우 있을 수 있습니다. 카운터 집합 은 매니페스트에 지정된 카운터 세트의 이름입니다. 생성된 Register 함수는 PrefixInitRegistrationInformationCounterset 함수를 호출하여 구조를 초기화 PCW_REGISTRATION_INFORMATION 한 다음, 를 호출 PcwRegister 하여 새 등록을 만들고 전역 Counterset 변수(예에서 CTRPP 생성 헤더 MyCounterset 에 선언됨)에 핸들을 저장합니다.

경우에 따라 CTRPP에서 생성된 Add 함수가 적절하지 않을 수 있습니다.

를 사용하여 컴파일 NTDDI_VERSION >= NTDDI_VERSION_FE 해야 하지만 이전 버전의 Windows에서 실행해야 하는 경우 CTRPP에서 생성된 Register 함수는 를 설정 RegInfo.Version = PCW_CURRENT_VERSION하기 때문에 작동하지 않습니다. PCW_CURRENT_VERSION 이NTDDI_VERSION >= NTDDI_VERSION_FE면 가 로 PCW_VERSION_2PcwRegister 설정되어 오류가 반환됩니다.
여러 카운터 세트 등록을 지원해야 하는 경우(예: 서버 사일로당 별도의 등록을 지원하려면) 반환된 핸들을 전역 변수에 저장하기 때문에 CTRPP에서 생성된 Register 함수가 작동하지 않습니다.
사일로 중립 카운터셋 등록을 만들려는 경우 를 호출PcwRegister하기 전에 값을 RegInfo.Flags 변경할 방법이 없으므로 CTRPP에서 생성된 Register 함수가 작동하지 않습니다.

이러한 경우 CTRPP 생성 Register 함수를 호출하는 대신 다음과 같은 코드를 사용합니다.

PCW_REGISTRATION_INFORMATION RegInfo;
InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

// Modify RegInfo as needed,
// e.g. RegInfo.Version = PCW_VERSION_1,
// or RegInfo.Flags = PcwRegistrationSiloNeutral.

// If needed, use another variable to store the handle instead of MyCounterset.
Status = PcwRegister(&MyCounterset, &RegInfo);

CTRPP에서 생성된 InitRegistrationInformationXxx 함수는 매니페스트의 RegInfo 선언에 따라 구조를 초기화합니다. 생성된 InitRegistrationInformation 함수에 대한 자세한 내용은 PCW_REGISTRATION_INFORMATION 설명서를 참조하세요.

Counterset 대신 사용자 고유의 핸들 변수를 사용하여 핸들을 저장하는 경우 CTRPP에서 생성된 Xxx 등록 취소 및 PcwCreateInstanceXxx만들기 함수를 사용하는 대신 및 를 직접 호출 PcwUnregister 해야 할 수도 있습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 7 및 이후 버전의 Windows에서 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL

추가 정보

PcwUnregister

_PCW_REGISTRATION_INFORMATION

다음을 통해 공유