PcwCreateInstance 함수(wdm.h)

  • 아티클

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

구문

NTSTATUS PcwCreateInstance(
  [out] PPCW_INSTANCE     *Instance,
  [in]  PPCW_REGISTRATION Registration,
  [in]  PCUNICODE_STRING  Name,
  [in]  ULONG             Count,
  [in]  PPCW_DATA         Data
);

매개 변수

[out] Instance

새로 만든 instance 받을 포인터입니다. pcwCloseInstance를 사용하여 instance 닫아야 합니다.

[in] Registration

이 instance 소유하는 카운터셋 등록에 대한 포인터입니다. 등록은 PcwRegister를 사용하여 만들어집니다.

[in] Name

카운터 세트의 instance 이름을 포함하는 유니코드 문자열에 대한 포인터입니다. NULL이 아니어야 합니다.

인스턴스 Name 값은 시간이 지남에 따라 안정적이어야 하며(동일한 논리 instance 콜백의 모든 호출에 대해 동일한 Name 값을 사용해야 함) 고유해야 합니다. 카운터 세트가 단일 instance 등록된 경우 instance Name 비어 있어야 합니다(0 길이). 카운터 세트가 다중 instance 등록된 경우 instance Name 비워 두면 안 됩니다. 인스턴스 이름 일치는 대/소문자를 구분하지 않으므로 Name 값이 대/소문자만 달라서는 안 됩니다.

[in] Count

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

[in] Data

이 instance 카운터 값을 포함하는 공급자 데이터 블록에 대한 설명자 배열입니다. 설명자가 참조하는 데이터 블록은 언제든지 액세스할 수 있으며 또는 PcwUnregister에 의해 PcwCloseInstance instance 닫을 때까지 유효한 상태를 유지해야 합니다.

반환 값

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

반환 코드 설명
STATUS_SUCCESS instance 성공적으로 만들어졌습니다.
STATUS_INVALID_PARAMETER_4 로 지정된 Count구조체 수가 등록된 공급자에 대해 유효하지 않습니다.
STATUS_INVALID_BUFFER_SIZE 공급자 데이터 블록 중 하나가 너무 작습니다. 예를 들어 PcwRegister를 호출하는 동안 공급자가 카운터 X 가 크기가 4바이트인 첫 번째 데이터 블록의 오프셋 100에 있음을 지정한다고 가정합니다. 호출 PcwCreateInstance 에서 첫 번째 데이터 블록이 50바이트임을 지정하면 이 오류 상태 반환됩니다.
STATUS_INTEGER_OVERFLOW 에 지정된 Count구조체의 크기는 데이터 버퍼를 오버플로합니다.

설명

카운터셋 공급자는 다음 두 가지 시스템을 통해 소비자에게 정보를 제공할 수 있습니다.

  • 공급자는 데이터를 수집하는 데 필요한 경우 성능 카운터 라이브러리에서 호출할 함수를 제공할 PCW_CALLBACK 수 있습니다. 이 시스템에 대한 자세한 내용은 PCW_CALLBACK 설명서를 참조하세요.
  • 공급자는 및 PcwCloseInstance 를 사용하여 PcwCreateInstance 사용 가능한 인스턴스 목록과 해당 카운터 데이터를 유지할 수 있습니다. 이 시스템은 구현이 간단하지만 유연성이 제한적입니다.

공급자가 이 함수를 사용하기 전에 공급자는 함수를 PcwRegister 호출하여 등록을 만들어야 합니다.

새 instance 도착하면(예: 디바이스가 연결된 경우) 공급자는 instance 대한 데이터 블록을 할당 및 초기화하고, instance 이름 및 데이터 블록을 사용하여 를 호출 PcwCreateInstance 한 다음, 데이터 블록의 값을 instance 카운터 값으로 업데이트된 상태로 유지해야 합니다. instance 유효하지 않은 경우(예: 디바이스가 분리된 경우) 공급자가 를 호출 PcwCloseInstance 한 다음 데이터 블록을 삭제해야 합니다.

공급자는 각 instance 대한 현재 카운터 값을 포함하는 데이터 블록(일반적으로 페이징 또는 비페이지 풀)을 유지 관리해야 합니다.

PcwCreateInstance는 instance 대한 고유 ID를 자동으로 할당합니다. instance ID에 대한 특정 값을 제공하려면 를 사용하는 PcwCreateInstance대신 함수를 PCW_CALLBACK 구현합니다.

PcwCloseInstance 함수를 사용하여 instance 닫습니다.

CTRPP에서 생성된 CreateXxx 함수

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

EXTERN_C __inline NTSTATUS
CreateMyCounterset(
    __deref_out PPCW_INSTANCE *Instance,
    __in PCUNICODE_STRING Name,
    __in const MY_COUNTER_DATA *MyCounterData
    )
{
    PCW_DATA Data[1];

    PAGED_CODE();

    Data[0].Data = MyCounterData;
    Data[0].Size = sizeof(MY_COUNTER_DATA);

    return PcwCreateInstance(Instance,
                             MyCounterset,
                             Name,
                             1,
                             Data);
}

CTRPP에서 생성된 Create 함수의 이름은 접두사CreateCounterset입니다. 접두 사는 일반적으로 비어 있지만 매개 변수가 -prefix CTRPP 명령줄에서 사용된 경우 있을 수 있습니다. 카운터 집합 은 매니페스트에 지정된 카운터 세트의 이름입니다. 함수에는 매니페스트에 정의된 구조체를 기반으로 하는 데이터 매개 변수가 있습니다. 함수는 사용자가 제공한 데이터 블록을 구조체 배열 PCW_DATA 로 래핑한 다음 를 호출 PcwCreateInstance합니다. 함수는 CTRPP에서 생성된 RegisterXxx 함수에 의해 초기화된 카운터셋 등록 핸들을 보유하는 전역 변수인 Counterset 변수(MyCounterset 예에서 참조)를 참조합니다.

요구 사항

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

추가 정보

PcwCloseInstance 함수

PcwRegister 함수