CTRPP

A ferramenta CTRPP é um pré-processador que analisa e valida o manifesto do provedor V2. A ferramenta gera .rc recursos com as cadeias de caracteres necessárias para os consumidores do seu provedor e gera um .h cabeçalho com código que você usa para fornecer seus dados de contador. Você deve executar a ferramenta CTRPP durante a compilação do provedor. Você deve usar o código gerado como ponto de partida ao desenvolver seu provedor em vez de tentar gerar esse código por conta própria.

ctrpp -o codeFile -rc rcFile [-legacy] [-MemoryRoutines] [-NotificationCallback] [-prefix prefix] [-ch symFile] [-backcompat] inputFile

Argumentos

Opção	Descrição
inputFile	Necessário: Especifica o nome do .man arquivo (manifesto XML) que define seus contadores.
-ocodeFile	Necessário: Especifica o nome do arquivo de .h código a ser gerado pelo CTRPP. Esse arquivo conterá funções auxiliares embutidas em C/C++ que simplificam a inicialização e a não inicialização do provedor.
-rcrcFile	Necessário: Especifica o nome do (arquivo de .rc recurso) a ser gerado pelo CTRPP. Esse arquivo conterá a tabela de cadeia de caracteres do provedor.
-chsymFile	Especifica o nome do arquivo de símbolo opcional .h a ser gerado pelo CTRPP. Esse arquivo conterá símbolos C/C++ para os nomes e GUIDs de cada contador no provedor.
-prefixo	Especifica o prefixo a ser usado para as variáveis e funções definidas no arquivo de cabeçalho gerado.
-NotificationCallback	Altera a assinatura padrão da função CounterInitialize para incluir parâmetros para especificar o nome das funções de retorno de chamada ControlCallback, AllocateMemory e FreeMemory . Esse argumento tem o mesmo efeito que incluir o callback atributo no elemento provider .
-migrateoutputFile	Em vez de gerar .h e .rc arquivos, atualiza o manifesto inputFile para a versão mais recente e o salva em outputFile. Essa opção não pode ser usada com outras opções. Uso: CTRPP -migrate NewFile.man OldFile.man
-BackCompat	Preterido: O suporte para provedores no modo kernel foi adicionado ao Windows 7. Por padrão, o código gerado pelo CTRPP para provedores no modo kernel será incompatível com versões anteriores do Windows (o driver falhará ao carregar devido a APIs ausentes Pcw*** ). Defina -BackCompat para habilitar a compatibilidade com versões anteriores do Windows. O driver carregará dinamicamente as APIs necessárias e o código gerado desabilitará silenciosamente o provedor se as APIs não estiverem disponíveis.
-MemoryRoutines	Preterido: Quando usado com a opção -Legacy , inclui modelos para rotinas de memória no código gerado. Caso contrário, esse argumento terá o mesmo efeito que a opção -NotificationCallback .
-Legado	Preterido:*.hGera arquivos , *.c, *.rce *_r.h usando os modelos de código do Windows Vista (gera PerfAutoInitialize e PerfAutoCleanup em vez de CounterInitialize e CounterCleanup). Essa opção pode ser usada com -MemoryRoutines e -NotificationCallback , mas não pode ser usada com nenhuma outra opção. Não use as opções -o ou -rc com essa opção. Os arquivos gerados serão nomeados com base no nome do manifesto e serão gravados no diretório que continha o manifesto. Uso: CTRPP -legacy OldFile.man

Comentários

A ferramenta CTRPP gera um .h arquivo de código, um .rc arquivo de recurso e, opcionalmente, gera um .h arquivo de símbolo.

Usando o arquivo de recurso gerado

A ferramenta CTRPP gerará um .rc arquivo de recurso que contém as cadeias de caracteres localizáveis necessárias pelos consumidores dos contadores do provedor.

Importante

Os recursos desse arquivo devem ser incluídos no binário do provedor e o caminho completo para o binário do provedor deve ser registrado durante a instalação do manifesto do provedor. Os consumidores que não conseguirem localizar e carregar os recursos não poderão usar os contadores do provedor.

Os recursos de cadeia de caracteres devem ser tratados da seguinte maneira:

• O desenvolvedor edita o arquivo de manifesto do provedor (.man) para definir o applicationIdentity atributo do provedor como o nome de um provedor binário (.DLL, .SYS ou .EXE) que conterá os recursos de cadeia de caracteres para o provedor e será instalado como parte do componente do provedor.
• A ferramenta CTRPP lê o manifesto do provedor e gera um .rc arquivo.
• A ferramenta RC (compilador de recursos) compila os dados do arquivo gerado por .rc CTRPP para gerar um .res arquivo que contém os recursos binários. Isso pode ser feito compilando diretamente o arquivo gerado .rc por CTRPP OU compilando outro .rc arquivo que inclui o arquivo gerado .rc por CTRPP por meio de uma #include diretiva .
• O vinculador insira os dados do arquivo gerado pelo .res RC no binário do provedor.
• Durante a instalação, o binário do provedor é copiado para o sistema do usuário e o manifesto do provedor é registrado usando a ferramenta lodctr. A ferramenta lodctr converte o applicationIdentity atributo do manifesto do provedor em um caminho completo e registra o caminho completo para o binário do provedor no registro.
  • Se o binário do provedor estiver no mesmo diretório que o manifesto, use: lodctr.exe /m:"C:\full\manifest\path\manifest.man". lodctr combinará o caminho de manifesto especificado com o atributo do applicationIdentity manifesto para formar o caminho completo.
  • Caso contrário, use lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path". lodctr combinará o caminho binário especificado com o atributo do applicationIdentity manifesto para formar o caminho completo.
  • Para fins de diagnóstico, você pode inspecionar o caminho completo registrado verificando o ApplicationIdentity valor da chave HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}do Registro.
  • Se o binário estiver usando MUI para localização, copie o arquivo MUI junto com o binário.
• Durante a coleta de contadores, o consumidor usa o caminho completo registrado para o binário do provedor para localizar e carregar as cadeias de caracteres necessárias dos recursos do binário do provedor.

Usando o arquivo de código gerado em um provedor de modo de usuário

A ferramenta CTRPP gerará um .h arquivo de código C/C++. Se o atributo do manifesto do providerType provedor estiver definido como userMode, o arquivo de código gerado conterá as seguintes definições úteis na codificação de um provedor de modo de usuário:

• Uma função de inicialização de provedor chamada CounterInitialize de prefixo.
• Uma função de limpeza do provedor chamada prefixoCounterCleanup.
• Uma variável de provedor global que armazena o identificador do provedor aberto pela função de prefixoCounterInitialize . O nome da variável é o valor do symbol atributo do provider elemento no manifesto. Essa variável deve ser usada em chamadas para PerfCreateInstance, PerfDeleteInstancee outras APIs para controlar os dados do provedor.
• Para cada contador, uma variável GUID de contador global com o GUID do contador. O nome da variável é o valor do counterSet atributo do symbol elemento mais o sufixo "GUID", por exemplo, MyCounterSetGUID. Essa variável deve ser usada em chamadas para PerfCreateInstance, PerfDeleteInstancee outras APIs para controlar os dados do provedor.
• Para cada contador, uma macro de contador com o valor do id contador. O nome da macro é o valor do counter atributo do symbol elemento. Essa macro deve ser usada em chamadas para PerfSetCounterRefValue, PerfSetULongLongCounterValuee outras APIs para definir os dados do provedor.

Nos nomes de função, prefixo refere-se ao valor do parâmetro de -prefix linha de comando. Se o -prefix parâmetro não for usado, as funções serão nomeadas CounterInitialize e CounterCleanup.

Usando o arquivo de código gerado em um provedor no modo kernel

A ferramenta CTRPP gerará um .h arquivo de código C/C++. Se o atributo do manifesto do providerType provedor estiver definido como kernelMode, o arquivo de código gerado conterá as seguintes definições que são úteis para codificar os contadores de um provedor de modo kernel:

• Uma função de inicialização de contraconjunto chamada prefixoRegister Counterset. Essa função preenche uma estrutura RegInfo e invoca PcwRegister, colocando o identificador de registro de contador resultante na variável Counterset global.
• Uma função de limpeza de conjunto de contadores chamada prefixoUnregister Counterset. Essa função invoca PcwUnregister no identificador de registro de contador na variável counterset global.
• Uma função de criação de instância chamada prefixoCreateCounterset. Essa função preenche uma matriz de estruturas PcwData e invoca PcwCreateInstance usando o identificador de registro de contador na variável counterset global.
• Uma função de limpeza de instância chamada prefixoCloseCounterset. Essa função invoca PcwCloseInstance.
• Uma função de relatório de instância chamada prefixoAddCounterset a ser usada na função de retorno de chamada de contraconjunto. Essa função preenche uma matriz de estruturas PcwData e invoca PcwAddInstance.
• SDK do Windows 20H1 e posterior: Uma função de inicialização RegInfo chamada prefixoInitRegistrationInformationCounterset para uso em cenários avançados. Essa função preenche uma estrutura RegInfo . Essa função pode ser usada em casos em que o prefixogeradoRegister Counterset não atende às suas necessidades, por exemplo, quando você deseja personalizar os valores na estrutura RegInfo ou quando deseja armazenar o identificador retornado em outra variável.

Nos nomes de função, prefixo refere-se ao valor do parâmetro de -prefix linha de comando. Se o -prefix parâmetro não for usado, as funções não terão nenhum prefixo.

Observação

A função addcounterset de prefixo gerada é usada quando você tem um retorno de chamada de contraconjunto. As funções createcounterset e prefixoclosecounterset geradas são usadas quando você não tem um retorno de chamada de contraconjunto.

Usando o arquivo de símbolo gerado

Se o parâmetro -ch for especificado na linha de comando, a ferramenta CTRPP gerará um arquivo de .h símbolo. Esse arquivo contém os símbolos C/C++ para os nomes e GUIDs de cada contador no provedor. Os símbolos podem ser usados ao escrever programas embutidos em código para consumir os dados desse contraconjunto usando as funções perfLib V2 Consumer.

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]