CTRPP

Средство CTRPP — это предварительный процессор, который анализирует и проверяет манифест для поставщика версии 2. Средство создает .rc ресурсы со строками, необходимыми потребителям поставщика, и создает .h заголовок с кодом, который используется для предоставления данных счетчика. Средство CTRPP следует запустить во время сборки поставщика. Созданный код следует использовать в качестве отправной точки при разработке поставщика, а не пытаться создавать его самостоятельно.

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

Аргументы

Параметр	Описание
inputFile	Обязательно: Указывает имя XML-файла манифеста .man , который определяет счетчики.
-ocodeFile	Обязательно: Указывает имя файла кода, создаваемого .h CTRPP. Этот файл будет содержать встроенные вспомогательные функции C/C++, которые упрощают инициализацию и неинициализацию поставщика.
-rcrcFile	Обязательно: Указывает имя файла ресурсов, .rc создаваемого CTRPP. Этот файл будет содержать строковую таблицу поставщика.
-chsymFile	Указывает имя необязательного .h файла символов, создаваемого CTRPP. Этот файл будет содержать символы C/C++ для имен и идентификаторов GUID каждого набора счетчиков в поставщике.
Префикс -prefix	Указывает префикс, используемый для переменных и функций, определенных в созданном файле заголовка.
-NotificationCallback	Изменяет сигнатуру функции CounterInitialize по умолчанию, включив параметры для указания имени функций обратного вызова ControlCallback, AllocateMemory и FreeMemory . Этот аргумент имеет тот же эффект, что и включение атрибута callback в элемент поставщика .
-migrateoutputFile	Вместо создания .h файлов и .rc обновляет манифест inputFile до последней версии и сохраняет его в outputFile. Этот параметр нельзя использовать с другими коммутаторами. Использование: CTRPP -migrate NewFile.man OldFile.man
-BackCompat	Устаревшие: В Windows 7 добавлена поддержка поставщиков режима ядра. По умолчанию код, созданный CTRPP для поставщиков режима ядра, будет несовместим с более ранними версиями Windows (драйвер не сможет загрузиться из-за отсутствия Pcw*** API). Задайте для -BackCompat обеспечения совместимости с более ранними версиями Windows. Драйвер будет динамически загружать необходимые API, а созданный код автоматически отключит поставщик, если api недоступны.
-MemoryRoutines	Устаревшие: При использовании с параметром -Legacy включает в созданный код шаблоны для подпрограмм памяти. В противном случае этот аргумент имеет тот же эффект, что и -NotificationCallback параметр .
-Наследие	Устаревшие: Создает *.hфайлы , *.c, *.rcи *_r.h с помощью шаблонов кода Windows Vista (создает PerfAutoInitialize и PerfAutoCleanup вместо CounterInitialize и CounterCleanup). Этот параметр можно использовать с -MemoryRoutines и -NotificationCallback , но не может использоваться с другими коммутаторами. Не используйте с этим параметром параметры -o или -rc . Созданные файлы будут называться на основе имени манифеста и записываться в каталог, содержащий манифест. Использование: CTRPP -legacy OldFile.man

Комментарии

Средство CTRPP создает .h файл кода, .rc файл ресурсов и при необходимости создает файл символов .h .

Использование созданного файла ресурсов

Средство CTRPP создаст .rc файл ресурсов, содержащий локализуемые строки, необходимые потребителям наборов счетчиков поставщика.

Важно!

Ресурсы из этого файла должны быть включены в двоичный файл поставщика, а полный путь к двоичному файлу поставщика должен быть зарегистрирован во время установки манифеста поставщика. Потребители, которые не могут найти и загрузить ресурсы, не смогут использовать наборы счетчиков поставщика.

Строковые ресурсы должны обрабатываться следующим образом:

• Разработчик изменяет файл манифеста поставщика (.man), чтобы задать applicationIdentity для атрибута поставщика имя двоичного файла поставщика (.DLL, .SYS или .EXE), который будет содержать строковые ресурсы для поставщика и будет установлен как часть компонента поставщика.
• Средство CTRPP считывает манифест поставщика и создает .rc файл.
• Средство-кандидат (компилятор ресурсов) компилирует данные из файла, созданного .rc CTRPP, для создания файла, .res содержащего двоичные ресурсы. Это можно сделать либо путем непосредственной компиляции файла, созданного .rc CTRPP, либо путем компиляции другого .rc файла, включающего файл, созданный .rc CTRPP, с помощью #include директивы .
• Компоновщик внедряет данные из файла, созданного rc-кандидатом .res , в двоичный файл поставщика.
• Во время установки двоичный файл поставщика копируется в систему пользователя, а манифест поставщика регистрируется с помощью средства lodctr. Средство lodctr преобразует applicationIdentity атрибут манифеста поставщика в полный путь и записывает полный путь в двоичный файл поставщика в реестре.
  • Если двоичный файл поставщика находится в том же каталоге, что и манифест, используйте: lodctr.exe /m:"C:\full\manifest\path\manifest.man". Lodctr объединит указанный путь манифеста с атрибутом манифеста applicationIdentity , чтобы сформировать полный путь.
  • В противном случае используйте коллекцию lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path". Lodctr объединит указанный двоичный путь с атрибутом манифеста applicationIdentity , чтобы сформировать полный путь.
  • В целях диагностики можно проверить записанный полный путь, проверив ApplicationIdentity значение раздела HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}реестра .
  • Если двоичный файл использует MUI для локализации, обязательно скопируйте файл MUI вместе с двоичным файлом.
• Во время сбора набора счетчиков потребитель использует записанный полный путь к двоичному файлу поставщика, чтобы найти и загрузить необходимые строки из ресурсов двоичного файла поставщика.

Использование созданного файла кода в поставщике пользовательского режима

Средство CTRPP создаст .h файл кода C/C++. Если атрибут манифеста providerType поставщика имеет значение userMode, созданный файл кода будет содержать следующие определения, которые полезны при написании кода поставщика пользовательского режима:

• Функция инициализации поставщика с именем prefixCounterInitialize.
• Функция очистки поставщика с именем префиксCounterCleanup.
• Глобальная переменная поставщика, которая хранит дескриптор поставщика, открытый функцией CounterInitialize. Имя переменной — это значение symbol атрибута provider элемента в манифесте. Эту переменную следует использовать в вызовах PerfCreateInstance, PerfDeleteInstanceи других API для управления данными поставщика.
• Для каждого набора счетчиков — это переменная GUID глобального набора счетчиков с идентификатором GUID набора счетчиков. Имя переменной — это значение counterSet атрибута symbol элемента, а также суффикс "GUID", например MyCounterSetGUID. Эту переменную следует использовать в вызовах PerfCreateInstance, PerfDeleteInstanceи других API для управления данными поставщика.
• Для каждого счетчика — макрос счетчика со значением счетчика id . Имя макроса — это значение counter атрибута symbol элемента. Этот макрос следует использовать в вызовах PerfSetCounterRefValue, PerfSetULongLongCounterValueи других API для настройки данных поставщика.

В именах функций префикс ссылается на значение параметра командной -prefix строки. -prefix Если параметр не используется, функции будут называться CounterInitialize и CounterCleanup.

Использование созданного файла кода в поставщике режима ядра

Средство CTRPP создаст .h файл кода C/C++. Если атрибут манифеста providerType поставщика имеет значение kernelMode, созданный файл кода будет содержать следующие определения, которые полезны при написании наборов счетчиков поставщика режима ядра:

• Функция инициализации набора счетчиков с именем prefixRegisterCounterset. Эта функция заполняет структуру RegInfo , а затем вызывает PcwRegister, помещая результирующий дескриптор регистрации набора счетчиков в глобальную переменную counterset .
• Функция очистки набора счетчиков с именем prefixUnregisterCounterset. Эта функция вызывает PcwUnregister для дескриптора регистрации набора счетчиков в глобальной переменной Counterset .
• Функция создания экземпляра с именем prefixCreateCounterset. Эта функция заполняет массив структур PcwData , а затем вызывает PcwCreateInstance с помощью дескриптора регистрации набора счетчиков в глобальной переменной Counterset .
• Функция очистки экземпляра с именем prefixCloseCounterset. Эта функция вызывает PcwCloseInstance.
• Функция создания отчетов экземпляра с именем prefixAddCounterset для использования из функции обратного вызова набора счетчиков. Эта функция заполняет массив структур PcwData , а затем вызывает PcwAddInstance.
• Windows SDK 20H1 и более поздних версий: Функция инициализации RegInfo с именем prefixInitRegistrationInformationCounterset для использования в расширенных сценариях. Эта функция заполняет структуру RegInfo . Эту функцию можно использовать в случаях, когда созданный префиксRegister Counterset не соответствует вашим потребностям, например, когда требуется настроить значения в структуре RegInfo или сохранить возвращенный дескриптор в другой переменной.

В именах функций префикс ссылается на значение параметра командной -prefix строки. -prefix Если параметр не используется, функции не будут иметь префикса.

Примечание

Созданная функция добавления счетчика префикса используется при обратном вызове набора счетчиков. Созданные функции префиксаCreateCounterset и PrefixCloseCounterset используются, если обратный вызов набора счетчиков отсутствует.

Использование созданного файла символов

Если параметр -ch указан в командной строке, средство CTRPP создаст файл символов .h . Этот файл содержит символы C/C++ для имен и guid каждого набора счетчиков в поставщике. Символы можно использовать при написании программ, которые жестко запрограммированы для использования данных из этого набора счетчиков с помощью функций PerfLib V2 Consumer.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]