Поделиться через


CTRPP

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

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

Аргументы

Вариант Описание
Файл ввода Обязательно: Указывает имя .man файла (XML manifest), определяющего счетчики.
-ocodeFile Обязательно: Указывает имя файла кода, .h который должен быть сгенерирован CTRPP. Этот файл будет содержать встроенные вспомогательные функции C/C++, которые упрощают инициализацию и отмену инициализации поставщика.
-rcrcФайл Обязательно: Указывает имя .rc (файла ресурсов), который должен быть сгенерирован CTRPP. Этот файл будет содержать таблицу строк поставщика.
-chsymFile Указывает имя необязательного .h файла символов, который должен быть сгенерирован CTRPP. Этот файл будет содержать символы C/C++ для имен и идентификаторов GUID каждого набора счетчиков в поставщике.
-префикс префикс Указывает префикс, используемый для переменных и функций, определенных в созданном файле заголовка.
-УведомлениеОбратный вызов Изменяет сигнатуру по умолчанию функции CounterInitialize , чтобы включить параметры для указания имени функций обратного вызова ControlCallback, AllocateMemory и FreeMemory . Этот аргумент имеет тот же эффект, что и включение атрибута callback в элемент поставщика .
-migrateoutputFile Вместо создания .h файлов и .rc обновляет манифест inputFile до последней версии и сохраняет его в outputFile. Этот переключатель нельзя использовать с другими переключателями. Использование: CTRPP -migrate NewFile.man OldFile.man
-Обратная Совместимость Устаревшие: В Windows 7 добавлена поддержка провайдеров режима ядра. По умолчанию код, сгенерированный CTRPP для провайдеров, работающих в режиме ядра, будет несовместим с более ранними версиями Windows (драйвер не будет загружаться из-за отсутствия Pcw*** API). Установите -BackCompat для включения совместимости с более ранними версиями Windows. Драйвер будет динамически загружать необходимые API, а сгенерированный код будет молча отключать провайдера, если API недоступны.
-MemoryRoutines Устаревшие: При использовании с переключателем -Legacy включает шаблоны для подпрограмм памяти в сгенерированный код. В противном случае этот аргумент имеет тот же эффект, что и -NotificationCallback switch.
-Наследство Устаревшие: Создает *.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 файл ресурсов, содержащий локализуемые строки, необходимые потребителям наборов счетчиков поставщика.

Это важно

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

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

  • Разработчик редактирует файл manifest (.man) поставщика, чтобы задать в качестве applicationIdentity атрибута поставщика имя двоичного файла поставщика (.DLL, .SYS или .EXE), который будет содержать строковые ресурсы для поставщика и будет установлен как часть компонента поставщика.
  • Средство CTRPP считывает манифест поставщика и создает .rc файл.
  • Инструмент RC (компилятор ресурсов) компилирует данные из файла, сгенерированного .rc CTRPP, для создания .res файла, содержащего двоичные ресурсы. Это можно сделать либо путем прямой компиляции файла, сгенерированного .rc CTRPP, либо путем компиляции другого .rc файла, который включает файл, сгенерированный .rc CTRPP, с помощью директивы #include .
  • Компоновщик встраивает данные из файла, созданного .res RC, в двоичный файл провайдера.
  • Во время установки двоичный файл поставщика копируется в систему пользователя, а манифест поставщика регистрируется с помощью средства 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 вместе с двоичным файлом.
  • Во время сбора counterset потребитель использует записанный полный путь к двоичному файлу поставщика для поиска и загрузки необходимых строк из ресурсов двоичного файла поставщика.

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

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

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

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

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

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

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

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

Замечание

Сгенерированный префиксAdd Counterset используется при наличии обратного вызова counterset. Созданные функции префиксаCreate Counterset и префиксаCloseCounterset используются, когда у вас нет обратного вызова counterset.

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

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

Требования

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