Compartilhar via

PM_COLLECT_PROC função de retorno de chamada (winperf.h)

  • Artigo

Coleta os dados de desempenho e os retorna ao consumidor. Implemente e exporte essa função se você estiver escrevendo uma DLL de desempenho para fornecer dados de desempenho. O sistema chama essa função sempre que um consumidor consulta o registro em busca de dados de desempenho.

A função CollectPerformanceData é um espaço reservado para o nome da função definida pelo aplicativo.

Sintaxe

PM_COLLECT_PROC PmCollectProc;

DWORD PmCollectProc(
                 LPWSTR pValueName,
                 void **ppData,
                 DWORD *pcbTotalBytes,
                 DWORD *pNumObjectTypes
)
{...}

Parâmetros

pValueName

ppData

pcbTotalBytes

pNumObjectTypes

Valor retornado

Um dos seguintes valores:

Código de retorno Descrição
ERROR_MORE_DATA O tamanho do buffer pData (em que pData se refere ao ponteiro apontado por lppData) conforme especificado por lpcbTotalBytes não é grande o suficiente para armazenar os dados. Deixe pData inalterado e defina lpcbTotalBytes e lpNumObjectTypes como zero. Nenhuma tentativa é feita para indicar o tamanho do buffer necessário, pois isso pode ser alterado antes da próxima chamada.
ERROR_SUCCESS Retorne esse valor em todos os casos diferentes do caso ERROR_MORE_DATA , mesmo que nenhum dado seja retornado ou ocorra um erro. Para relatar erros diferentes do tamanho insuficiente do buffer, use o Log de Eventos do Aplicativo.

Comentários

Se os objetos solicitados especificados no parâmetro lpValueName não corresponderem a nenhum dos índices de objeto aos quais a DLL de desempenho dá suporte, deixe o parâmetro pData inalterado (em que pData se refere ao ponteiro apontado por lppData) e defina os parâmetros lpcbTotalBytes e lpNumObjectTypes como zero. Isso indica que nenhum dado foi retornado.

Se você der suporte a um ou mais dos objetos consultados, determine se o tamanho do buffer pData conforme especificado por lpcbTotalBytes é grande o suficiente para armazenar os dados. Caso contrário, deixe pData inalterado e defina lpcbTotalBytes e lpNumObjectTypes como zero. Nenhuma tentativa é feita para indicar o tamanho do buffer necessário, pois isso pode mudar antes da próxima chamada. Retornar ERROR_MORE_DATA.

Se a coleta de dados for demorada, você deverá responder apenas a consultas para objetos específicos ou consultas dispendiosas. Você também deve reduzir a prioridade do thread que coleta os dados, para que eles não afetem negativamente o desempenho do sistema. Para o formato de cadeia de caracteres de consulta, consulte Usando as funções do Registro para consumir dados de contador.

Se o consumidor estiver em execução em outro computador (remotamente), as funções OpenPerformanceData, ClosePerformanceData e CollectPerformanceData serão chamadas no contexto do processo winlogon, que manipula o lado do servidor da conexão remota. Essa distinção é importante ao solucionar problemas que ocorrem apenas remotamente.

Depois que a função retornar com êxito, o sistema poderá executar alguns testes básicos para garantir a integridade dos dados. Por padrão, nenhum teste é executado. Se um teste falhar, o sistema gerará uma mensagem de log de eventos e os dados serão descartados para evitar problemas adicionais devido a ponteiros que não são válidos. O seguinte valor do Registro controla o nível de teste: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Perflib\ExtCounterTestLevel.

Veja a seguir os possíveis níveis de teste para ExtCounterTestLevel.

Nível Significado
1 Teste os ponteiros e buffers de DLLs de contador confiável. Envia uma cópia do buffer do usuário.
2 Testar ponteiros e comprimentos de buffer, mas não testa referências de ponteiro ou conteúdo do buffer. Envia uma cópia do buffer do usuário.
3 Não teste ponteiros ou buffers. Envia uma cópia do buffer do usuário.
4 Não teste ponteiros ou buffers. Envia o buffer do usuário, não uma cópia. Esse é o valor padrão.

Os seguintes testes são executados nos níveis 1 e 2:

  • Verifica se o valor de lpcbTotalBytes é consistente com o ponteiro de buffer retornado, pData. Se você adicionar o valor lpcbTotalBytes ao ponteiro de buffer original passado para essa função, deverá acabar com o mesmo ponteiro de buffer retornado por essa função. Se eles não forem iguais, uma mensagem de erro será registrada e os dados serão ignorados.
  • Verifique se um estouro de buffer não ocorreu. O sistema adiciona uma página de proteção de 1 KB antes e depois do buffer alocado pelo consumidor. Se o ponteiro de buffer retornado, pData, apontar para além do primeiro byte da página de proteção acrescentada, supõe-se que o buffer não é válido e os dados são ignorados. Se o ponteiro do buffer exceder o final do buffer, mas não o final da página de proteção, um erro de estouro de buffer será registrado. Se o ponteiro do buffer estiver além do final da página de proteção, um erro de heap será registrado porque o heap do qual o buffer foi alocado pode ter sido corrompido, causando outros erros de memória.
  • Verifique se as páginas de proteção não foram corrompidas. As páginas de proteção de 1 KB que foram adicionadas antes e depois do buffer são inicializadas com um padrão de dados antes que essa função seja chamada. Esse padrão de dados é verificado após o retorno do procedimento de coleta. Se alguma discrepância for detectada, um estouro de buffer ou outro erro de memória será assumido e os dados serão ignorados.

Os seguintes testes serão executados somente se o nível de teste 1 for usado:

  • Verifique se a soma do membro TotalByteLength de cada objeto é igual ao valor de lpcbTotalBytes. Caso contrário, os dados serão ignorados.
  • Verifique se o membro ByteLength de cada instância é consistente. Os comprimentos serão consistentes se o próximo objeto ou fim do buffer seguir a última instância. Caso contrário, os dados serão ignorados.

Exemplos

Consulte Implementando CollectPerformanceData.

Requisitos

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

Confira também