PcwAddInstance 함수(wdm.h)

아티클
08/08/2023

함수는 PcwAddInstance 카운터 세트의 지정된 instance 소비자 버퍼에 추가합니다. 대부분의 개발자는 이 함수를 직접 호출하는 대신 CTRPP에서 생성된 AddXxx 함수를 사용합니다. 자세한 내용은 아래 설명을 참조하세요.

구문

NTSTATUS PcwAddInstance(
  [in] PPCW_BUFFER      Buffer,
  [in] PCUNICODE_STRING Name,
  [in] ULONG            Id,
  [in] ULONG            Count,
  [in] PPCW_DATA        Data
);

매개 변수

[in] Buffer

카운터 세트의 instance 추가할 시스템 관리 버퍼에 대한 핸들입니다. 버퍼가 알림에서 PcwCallbackEnumerateInstances 오는 경우 는 PcwAddInstance instance 이름 및 ID만 기록합니다. 버퍼가 알림에서 PcwCallbackCollectData 오는 경우 는 PcwAddInstance instance 이름, ID 및 데이터(카운터 값)를 기록합니다.

[in] Name

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

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

[in] Id

카운터 세트 instance 연결된 (식별자)를 지정 Id 하는 숫자 값입니다.

인스턴스 Id 값은 시간이 지남에 따라 안정적이어야 하며(동일한 instance 콜백의 모든 호출에 대해 동일한 Id 값을 사용해야 함), 고유해야 하고(예: 모든 인스턴스에 0을 사용하지 않음) 0xFFFFFFFE 미만이어야 합니다(인스턴스에 사용하지 PCW_ANY_INSTANCE_ID 않음). 가능하면 instance Id 의미 있어야 합니다(예: 프로세스 카운터 세트는 임의(예: 시퀀스 번호) 대신 PIDId를 로 사용할 수 있음).

[in] Count

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

[in] Data

이 instance 카운터 값을 포함하는 공급자 데이터 블록에 대한 설명자 배열입니다.

반환 값

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

반환 코드	설명
`STATUS_SUCCESS`	instance 버퍼에 성공적으로 추가되었습니다.
`STATUS_INVALID_BUFFER_SIZE`	공급자 데이터 블록 중 하나가 너무 작습니다. 예를 들어 PcwRegister를 호출하는 동안 공급자가 카운터 `X` 가 크기 4바이트인 첫 번째 데이터 블록의 오프셋 100에 있음을 지정한다고 가정합니다. 에 대한 `PcwAddInstance` 호출에서 첫 번째 데이터 블록이 50바이트임을 지정하면 이 오류 상태 반환됩니다.

설명

알림 유형 PcwCallbackEnumerateInstances 이 PcwAddInstance 또는 PcwCallbackCollectData인 경우 공급자 정의 PCW_CALLBACK 루틴에서 함수를 호출해야 합니다. 사용할 은 Buffer 루틴에 Info 대한 PCW_CALLBACK 매개 변수(예: 또는 Info->CollectData.Buffer)에서 제공됩니다. Info->EnumerateInstances.Buffer

알림을 PcwAddInstance 호출하면 PcwCallbackEnumerateInstances 및 Id 값을 버퍼에 추가합니다Name. 알림을 PcwAddInstance 호출하면 PcwCallbackCollectData , Id및 카운터 데이터 값을 버퍼에 추가합니다Name.

CTRPP 생성 Add*** 함수

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

EXTERN_C __inline NTSTATUS
AddMyCounterset(
    __in PPCW_BUFFER Buffer,
    __in PCUNICODE_STRING Name,
    __in ULONG Id,
    __in_opt const MY_COUNTER_DATA *MyCounterData
    )
{
    PCW_DATA Data[1];

    PAGED_CODE();

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

    return PcwAddInstance(Buffer,
                          Name,
                          Id,
                          1,
                          Data);
}

CTRPP 생성 Add 함수의 이름은 접두사카운터 세트 추가입니다. 접두 사는 일반적으로 비어 있지만 매개 변수가 -prefix CTRPP 명령줄에서 사용된 경우 있을 수 있습니다. Counterset 은 매니페스트에 지정된 카운터 세트의 이름입니다. 함수에는 매니페스트에 정의된 구조체를 기반으로 하는 데이터 매개 변수가 있습니다. 함수는 사용자가 제공한 데이터 블록을 구조체 배열 PCW_DATA 로 래핑한 다음 를 호출 PcwAddInstance합니다.

요구 사항

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

추가 정보

PCW_CALLBACK 콜백 함수

다음을 통해 공유