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
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:*.h Gera arquivos , *.c , *.rc e *_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 |
A ferramenta CTRPP gera um .h
arquivo de código, um .rc
arquivo de recurso e, opcionalmente, gera um .h
arquivo de símbolo.
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 oapplicationIdentity
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 doapplicationIdentity
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 doapplicationIdentity
manifesto para formar o caminho completo. - Para fins de diagnóstico, você pode inspecionar o caminho completo registrado verificando o
ApplicationIdentity
valor da chaveHKEY_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.
- Se o binário do provedor estiver no mesmo diretório que o manifesto, use:
- 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.
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 doprovider
elemento no manifesto. Essa variável deve ser usada em chamadas paraPerfCreateInstance
,PerfDeleteInstance
e 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 dosymbol
elemento mais o sufixo "GUID", por exemplo,MyCounterSetGUID
. Essa variável deve ser usada em chamadas paraPerfCreateInstance
,PerfDeleteInstance
e 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 docounter
atributo dosymbol
elemento. Essa macro deve ser usada em chamadas paraPerfSetCounterRefValue
,PerfSetULongLongCounterValue
e 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
.
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.
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.
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] |