Функция MsiFormatRecordA (msiquery.h)

Статья
08/25/2023

Функция MsiFormatRecord форматирует данные и свойства полей записи с помощью строки формата.

Синтаксис

UINT MsiFormatRecordA(
  [in]      MSIHANDLE hInstall,
  [in]      MSIHANDLE hRecord,
  [out]     LPSTR     szResultBuf,
  [in, out] LPDWORD   pcchResultBuf
);

Параметры

[in] hInstall

Дескриптор установки. Это можно опустить. В этом случае обрабатываются только параметры поля записи, а свойства недоступны для подстановки.

[in] hRecord

Дескриптор записи для форматирования. Строка шаблона должна храниться в поле записи 0, за которым следуют параметры данных, на которые указывает ссылка.

[out] szResultBuf

Указатель на буфер, получающий строку форматирования с завершением NULL. Не пытайтесь определить размер буфера, передав значение NULL (value=0) для szResultBuf. Размер буфера можно получить, передав пустую строку (например, ""). Затем функция возвращает ERROR_MORE_DATA и pcchResultBuf содержит требуемый размер буфера в TCHAR, не включая завершающий символ NULL. При возврате ERROR_SUCCESSpcchResultBuf содержит число записываемых в буфер TCHAR, не включая завершающий символ NULL.

[in, out] pcchResultBuf

Указатель на переменную, указывающую размер буфера в TCHAR, на который указывает переменная szResultBuf. Когда функция возвращает ERROR_SUCCESS, эта переменная содержит размер данных, скопированных в szResultBuf, не включая завершающий символ NULL. Если szResultBuf недостаточно велик, функция возвращает ERROR_MORE_DATA и сохраняет требуемый размер, не включая завершающий символ NULL, в переменной, на которую указывает pcchResultBuf.

Возвращаемое значение

Функция MsiFormatRecord возвращает одно из следующих значений:

Параметры, которые должны быть отформатированы , заключаются в квадратные скобки [...]. Квадратные скобки могут быть итерированы, так как подстановки разрешаются изнутри.

Если часть строки заключена в фигурные скобки { } и не содержит квадратных скобок, она остается без изменений, включая фигурные скобки.

Если часть строки заключена в фигурные скобки { } и содержит одно или несколько имен свойств, а все свойства найдены, текст (с разрешенными подстановками) отображается без фигурных скобок. Если какое-либо из свойств не найдено, весь текст в фигурных скобках и сами фигурные скобки удаляются.

Обратите внимание, что в случае отложенного выполнения пользовательских действий MsiFormatRecord поддерживает только свойства CustomActionData и ProductCode . Дополнительные сведения см. в разделе Получение сведений о контексте для пользовательских действий с отложенным выполнением.

Ниже описано, как форматировать строки с помощью функции MsiFormatRecord .

Форматирование строк с помощью функции MsiFormatRecord

Числовые параметры заменяются заменой маркера значением соответствующего поля записи с отсутствующими значениями или значениями NULL, не образующими текста.
Итоговая строка обрабатывается путем замены неуписанных параметров соответствующими значениями, описанными далее.
- Если обнаружена подстрока формы "[propertyname]", она заменяется значением свойства .
- При обнаружении подстроки формы "[%environmentvariable]" значение переменной среды подставляется.
- Если найдена подстрока формы "[#filekey]", она заменяется полным путем к файлу со значением filekey , используемым в качестве ключа в таблице File. Значение "[#filekey]" остается пустым и не заменяется путем, пока установщик не запустит действия CostInitialize, FileCost и CostFinalize. Значение "[#filekey]" зависит от состояния установки компонента, которому принадлежит файл. Если компонент выполняется из источника, значением является путь к исходному расположению файла. Если компонент запускается локально, значением является путь к целевому расположению файла после установки. Если компонент отсутствует, путь пустой. Дополнительные сведения о проверке состояния установки компонентов см. в разделе Проверка установки компонентов, компонентов, файлов.
- Если подстрока формы "[$componentkey]" найдена, она заменяется каталогом установки компонента со значением componentkey , используемым в качестве ключа в таблице Component. Значение "[$componentkey]" остается пустым и не заменяется каталогом, пока установщик не запустит действия CostInitialize, FileCost и CostFinalize. Значение "[$componentkey]" зависит от состояния установки компонента. Если компонент выполняется из источника, значением является исходный каталог файла. Если компонент запускается локально, значением будет целевой каталог после установки. Если компонент отсутствует, значение остается пустым. Дополнительные сведения о проверке состояния установки компонентов см. в разделе Проверка установки компонентов, компонентов, файлов.
- Обратите внимание, что если компонент уже установлен и не переустанавливается, не удаляется или не перемещается во время текущей установки, то состояние действия компонента равно NULL и, следовательно, строка "[$componentkey]" принимает значение Null.
- Если подстрока формы "[\c]" найдена, она заменяется символом без дальнейшей обработки. Сохраняется только первый символ после обратной косой черты; все остальное удаляется.

Если возвращается ERROR_MORE_DATA , параметр, являющийся указателем, задает размер буфера, необходимый для хранения строки. Если возвращается ERROR_SUCCESS , он указывает количество символов, записанных в буфер строк. Поэтому размер буфера можно получить, передав пустую строку (например, "") для параметра, задающего буфер. Не пытайтесь определить размер буфера путем передачи значения Null (value=0).

Примечание

Заголовок msiquery.h определяет MsiFormatRecord как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Установщик Windows 5.0 в Windows Server 2012, Windows 8, Windows Server 2008 R2 или Windows 7. Установщик Windows 4.0 или Установщик Windows 4.5 в Windows Server 2008 или Windows Vista.
Целевая платформа	Windows
Header	msiquery.h
Библиотека	Msi.lib
DLL	Msi.dll

См. также раздел

Передача null в качестве аргумента функций установщика Windows