PERFLIBREQUEST 콜백 함수(perflib.h)

  • 아티클

공급자는 소비자가 쿼리에서 카운터 추가 또는 제거와 같은 특정 작업을 수행할 때 알림을 수신하도록 이 함수를 구현할 수 있습니다. PERFLIB는 소비자의 요청이 완료되기 전에 콜백을 호출합니다.

PERFLIBREQUEST 형식은 이 콜백 함수에 대한 포인터를 정의합니다. ControlCallback 함수는 애플리케이션 정의 함수 이름의 자리 표시자입니다.

구문

PERFLIBREQUEST Perflibrequest;

ULONG Perflibrequest(
  [in] ULONG RequestCode,
  [in] PVOID Buffer,
  [in] ULONG BufferSize
)
{...}

매개 변수

[in] RequestCode

요청 코드는 다음 값 중 하나일 수 있습니다.

값 의미
PERF_ADD_COUNTER
 소비자가 쿼리에 카운터를 추가합니다. PERFLIB는 쿼리에 추가되는 각 카운터에 대해 이 요청 코드를 사용하여 콜백을 호출합니다. Buffer 매개 변수에는 추가되는 카운터를 식별하는 PERF_COUNTER_IDENTITY 구조체가 포함되어 있습니다.

공급자는 이 알림을 사용하여 계산을 시작할 수 있습니다.
PERF_REMOVE_COUNTER
 소비자가 쿼리에서 카운터를 제거합니다. PERFLIB는 쿼리에서 제거되는 각 카운터에 대해 이 요청 코드를 사용하여 콜백을 호출합니다. Buffer 매개 변수에는 제거되는 카운터를 식별하는 PERF_COUNTER_IDENTITY 구조체가 포함되어 있습니다.

공급자는 이 알림을 사용하여 계산을 중지할 수 있습니다.
PERF_ENUM_INSTANCES
 소비자가 카운터 집합의 인스턴스를 열거하고 있습니다. Buffer 매개 변수에는 소비자가 인스턴스를 열거하는 컴퓨터(또는 해당 IP 주소)의 이름을 식별하는 null로 끝나는 유니코드 문자열이 포함되어 있습니다.
PERF_COLLECT_START
 소비자가 카운터 데이터를 수집하기 시작했습니다. Buffer 매개 변수에는 소비자가 데이터를 수집하는 컴퓨터의 이름(또는 해당 IP 주소)을 식별하는 null로 끝나는 유니코드 문자열이 포함되어 있습니다.

공급자는 원시 데이터 상태가 중요한 경우(예: 부분 업데이트가 허용되지 않는 트랜잭션 관련 카운터) 이 알림을 사용할 수 있습니다. 이 알림을 통해 공급자는 보류 중인 모든 업데이트를 플러시하고 컬렉션이 시작되기 전에 향후 업데이트를 잠글 수 있습니다.
PERF_COLLECT_END
 카운터 데이터 수집이 완료되었습니다. Buffer 매개 변수에는 소비자가 데이터를 수집한 컴퓨터의 이름(또는 해당 IP 주소)을 식별하는 null로 끝나는 유니코드 문자열이 포함되어 있습니다.

공급자는 이 알림을 사용하여 카운터 데이터에 대한 업데이트를 다시 시작할 수 있도록 컬렉션 시작 알림에 의해 부과된 업데이트 잠금을 해제할 수 있습니다.

[in] Buffer

버퍼의 내용은 요청에 따라 달라집니다. 가능한 콘텐츠는 RequestCode 매개 변수를 참조하세요.

[in] BufferSize

Buffer 매개 변수의 크기(바이트)입니다.

반환 값

콜백이 성공하면 ERROR_SUCCESS 반환합니다.

콜백이 실패하면 요청이 PERF_ADD_COUNTER, PERF_ENUM_INSTANCES또는PERF_COLLECT_START 경우 PERFLIB는 오류 코드를 소비자에게 반환합니다. 그렇지 않으면 오류 코드가 무시됩니다.

설명

공급자 요소의 콜백 특성이 "custom"이거나 CTRPP를 호출할 때 -NotificationCallback 인수를 사용한 경우 이 함수를 구현해야 합니다. 콜백 함수의 이름을 CounterInitialize에 전달합니다.

Windows Vista: CounterInitialize 함수의 이름은 PerfAutoInitialize입니다. 또한 CTRPP 도구는 모든 요청 코드를 포함하는 이 콜백의 기본 구조를 생성합니다. 그런 다음 지원하려는 요청 코드에 코드를 추가하고 다른 코드를 제거합니다.

콜백은 1초 이내에 완료되어야 합니다. 콜백이 정시에 완료되지 않으면 PERFLIB는 소비자의 요청을 계속 수행하고 콜백이 완료되면 콜백의 반환 값을 무시합니다.

예제

다음 예제에서는 ControlCallback 함수의 간단한 구현을 보여줍니다.

ULONG MyControlCallback(ULONG RequestCode, PVOID pBuffer, ULONG* pBufferSize)
{
    ULONG Status = ERROR_SUCCESS;
    PWNODE_HEADER Wnode = (PWNODE_HEADER)pBuffer;
    LPWSTR pComputerName = NULL;
    LPWSTR pInstance = NULL;
    PPERF_COUNTER_IDENTITY pCounter;
    UNREFERENCED_PARAMETER(pBufferSize);

    switch (RequestCode) 
    {
        case PERF_ADD_COUNTER:
            pCounter = (PPERF_COUNTER_IDENTITY)(((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            pComputerName = (LPWSTR)(((LPBYTE) pCounter) + pCounter->MachineOffset);
            pInstance = (pCounter->NameOffset > 0) 
                ? (LPWSTR) (((LPBYTE) pCounter) + pCounter->NameOffset) : NULL;
            
            break;

        case PERF_REMOVE_COUNTER: 
            pCounter = (PPERF_COUNTER_IDENTITY)(((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            pComputerName = (LPWSTR)(((LPBYTE) pCounter) + pCounter->MachineOffset);
            pInstance = (pCounter->NameOffset > 0)
                ? (LPWSTR) (((LPBYTE) pCounter) + pCounter->NameOffset) : NULL;
            
            break;

        case PERF_ENUM_INSTANCES:
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        case PERF_COLLECT_START: 
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        case PERF_COLLECT_END: 
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        default:
            wprintf(L"Unknown request code, %lu\n", RequestCode);
    }

    return Status;
}

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버 Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼 Windows
헤더 perflib.h