Função de retorno de chamada PERFLIBREQUEST (perflib.h)

Os provedores podem implementar essa função para receber notificação quando os consumidores executam determinadas ações, como adicionar ou remover contadores de uma consulta. O PERFLIB chama o retorno de chamada antes que a solicitação do consumidor seja concluída.

O tipo PERFLIBREQUEST define um ponteiro para essa função de retorno de chamada. A função ControlCallback é um espaço reservado para o nome da função definida pelo aplicativo.

Sintaxe

PERFLIBREQUEST Perflibrequest;

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

Parâmetros

[in] RequestCode

O código de solicitação pode ser um dos valores a seguir.

Valor	Significado
PERF_ADD_COUNTER	O consumidor está adicionando um contador à consulta. O PERFLIB chama o retorno de chamada com esse código de solicitação para cada contador que está sendo adicionado à consulta. O parâmetro Buffer contém uma estrutura PERF_COUNTER_IDENTITY que identifica o contador que está sendo adicionado. Os provedores podem usar essa notificação para iniciar a contagem.
PERF_REMOVE_COUNTER	O consumidor está removendo um contador da consulta. PERFLIB chama o retorno de chamada com esse código de solicitação para cada contador que está sendo removido da consulta. O parâmetro Buffer contém uma estrutura PERF_COUNTER_IDENTITY que identifica o contador que está sendo removido. Os provedores podem usar essa notificação para interromper a contagem.
PERF_ENUM_INSTANCES	O consumidor está enumerando instâncias do conjunto de contadores. O parâmetro Buffer contém uma cadeia de caracteres Unicode terminada em nulo que identifica o nome do computador (ou seu endereço IP) do qual o consumidor está enumerando as instâncias.
PERF_COLLECT_START	O consumidor está começando a coletar dados do contador. O parâmetro Buffer contém uma cadeia de caracteres Unicode terminada em nulo que identifica o nome do computador (ou seu endereço IP) do qual o consumidor está coletando dados. Os provedores poderão usar essa notificação se o estado de dados brutos for crítico (por exemplo, contadores relacionados a transações em que atualizações parciais não são permitidas). Essa notificação dá ao provedor a chance de liberar todas as atualizações pendentes e bloquear atualizações futuras antes do início da coleção.
PERF_COLLECT_END	A coleta de dados do contador está concluída. O parâmetro Buffer contém uma cadeia de caracteres Unicode terminada em nulo que identifica o nome do computador (ou seu endereço IP) do qual o consumidor coletou dados. Os provedores podem usar essa notificação para liberar o bloqueio de atualização imposto pela notificação de início da coleção para que as atualizações nos dados do contador possam ser retomadas.

[in] Buffer

O conteúdo do buffer depende da solicitação. Para obter conteúdo possível, consulte o parâmetro RequestCode .

[in] BufferSize

Tamanho, em bytes, do parâmetro Buffer .

Retornar valor

Retorne ERROR_SUCCESS se o retorno de chamada for bem-sucedido.

Se o retorno de chamada falhar, o PERFLIB retornará o código de erro ao consumidor se a solicitação for PERF_ADD_COUNTER, PERF_ENUM_INSTANCES ou PERF_COLLECT_START; caso contrário, o código de erro será ignorado.

Comentários

Se o atributo de retorno de chamada do elemento provider for "personalizado" ou você tiver usado o argumento -NotificationCallback ao chamar CTRPP, deverá implementar essa função. Você passa o nome da função de retorno de chamada para CounterInitialize.

Windows Vista: A função CounterInitialize é denominada PerfAutoInitialize. A ferramenta CTRPP também gera um esqueleto desse retorno de chamada para você que inclui todos os códigos de solicitação. Em seguida, adicione código aos códigos de solicitação aos quais deseja dar suporte e remova os outros.

O retorno de chamada deve ser concluído em um segundo. Se o retorno de chamada não for concluído a tempo, o PERFLIB continuará com a solicitação do consumidor e ignorará o valor retornado do retorno de chamada quando ele for concluído.

Exemplos

O exemplo a seguir mostra uma implementação simples de uma função 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;
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	perflib.h