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

Статья
03/05/2024

Функция MsiProcessMessage отправляет в установщик запись об ошибке для обработки.

Синтаксис

int MsiProcessMessage(
  [in] MSIHANDLE      hInstall,
  [in] INSTALLMESSAGE eMessageType,
  [in] MSIHANDLE      hRecord
);

Параметры

[in] hInstall

Дескриптор установки, предоставленной пользовательскому действию DLL или полученной через MsiOpenPackage, MsiOpenPackageEx или MsiOpenProduct.

[in] eMessageType

Параметр eMessage должен быть значением, указывающим один из следующих типов сообщений. Чтобы отобразить окно сообщения с кнопками или значками, используйте операторы OR для добавления INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING или INSTALLMESSAGE_USER в стандартные стили окна сообщений, используемые функциями MessageBox и MessageBoxEx . Дополнительные сведения см. в примечаниях ниже.

Значение	Значение
INSTALLMESSAGE_FATALEXIT	Преждевременное завершение, возможно, неустранимая нехватка памяти.
INSTALLMESSAGE_ERROR	Форматированные сообщения об ошибке, [1] — номер сообщения в таблице ошибок.
INSTALLMESSAGE_WARNING	Форматируемо предупреждающее сообщение, [1] — номер сообщения в таблице ошибок.
INSTALLMESSAGE_USER	Сообщение о запросе пользователя, [1] — номер сообщения в таблице ошибок.
INSTALLMESSAGE_INFO	Информативное сообщение для журнала, не должны отображаться.
INSTALLMESSAGE_FILESINUSE	Список используемых в настоящее время файлов, которые необходимо закрыть перед заменой.
INSTALLMESSAGE_RESOLVESOURCE	Запрос на определение допустимого расположения источника.
INSTALLMESSAGE_RMFILESINUSE	Список используемых в настоящее время файлов, которые необходимо закрыть перед заменой. Доступно начиная с установщика Windows версии 4.0. Дополнительные сведения об этом сообщении см. в статье Использование диспетчера перезапуска с внешним пользовательским интерфейсом.
INSTALLMESSAGE_OUTOFDISKSPACE	Сообщение о нехватке места на диске.
INSTALLMESSAGE_ACTIONSTART	Ход выполнения: начало действия, [1] имя действия, [2] описание, [3] Шаблон для сообщений ACTIONDATA.
INSTALLMESSAGE_ACTIONDATA	Данные действия. Поля записей соответствуют шаблону сообщения ACTIONSTART.
INSTALLMESSAGE_PROGRESS	Сведения о индикаторе выполнения. См. описание полей записей ниже.
INSTALLMESSAGE_COMMONDATA	Чтобы включить кнопку Отмена, задайте для параметра [1] значение 2, а для [2] значение 1. Чтобы отключить кнопку Отмена, задайте для параметра [1] значение 2, а для [2] — значение 0

[in] hRecord

Дескриптор записи, содержащей формат сообщения и данные.

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

Эта функция возвращает int.

Функция MsiProcessMessage выполняет все включенные операции ведения журнала и откладывает выполнение. Вы можете выборочно включить ведение журнала для различных типов сообщений.

Для INSTALLMESSAGE_FATALEXIT, INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING и INSTALLMESSAGE_USER сообщений, если поле 0 не задано, для поля 1 должен быть задан код ошибки, соответствующий сообщению об ошибке в таблице Ошибка. Затем сообщение форматируется с помощью шаблона из таблицы Error перед его передачей в обработчик пользовательского интерфейса для отображения.

Поля записи для сообщений индикатора выполнения

Ниже описаны поля записей, если для eMessageType задано значение INSTALLMESSAGE_PROGRESS. Поле 1 указывает тип сообщения о ходе выполнения. Значение других полей зависит от значения в этом поле. Ниже приведены возможные значения, которые можно задать в поле 1.

Значение поля 1	Описание поля 1
0	Сбрасывает индикатор выполнения и задает ожидаемое общее количество тактов на панели.
1	Предоставляет сведения, связанные с сообщениями о ходе выполнения, отправляемых текущим действием.
2	Увеличивает индикатор выполнения.
3	Позволяет действию (например, CustomAction) добавлять такты к ожидаемому общему количеству хода выполнения индикатора выполнения.

Значение поля 2 зависит от значения в поле 1, как показано ниже.

Значение поля 1	Описание поля 2
0	Ожидаемое общее количество тактов на индикаторе выполнения.
1	Число тактов, перемещаемых индикатором выполнения для каждого сообщения ActionData, отправленного текущим действием. Это поле игнорируется, если поле 3 равно 0.
2	Количество тактов, которое перемещено индикатором выполнения.
3	Количество тактов, добавляемых к общему ожидаемому ходу выполнения.

Значение поля 3 зависит от значения в поле 1 следующим образом.

Значение поля 1	Значение поля 3	Описание поля 3
0	0	Индикатор выполнения вперед (слева направо)
	1	Индикатор выполнения назад (справа налево)
1	0	Текущее действие будет отправлять явные сообщения ProgressReport.
	1	Увеличьте индикатор выполнения на количество тактов, указанное в поле 2, каждый раз, когда текущее действие отправляет сообщение ActionData.
2	Не используется
3	Не используется

Значение поля 4 зависит от значения в поле 1 следующим образом.

Значение поля 1	Значение поля 4	Описание поля 4
0	0	Выполняется. В этом случае пользовательский интерфейс может вычислить и отобразить оставшееся время.
	1	Создание скрипта выполнения. В этом случае в пользовательском интерфейсе может отображаться сообщение о том, что нужно подождать, пока установщик завершит подготовку установки.
1	Не используется
2	Не используется
3	Не используется

Дополнительные сведения и пример кода см. в разделе Добавление настраиваемых действий в ProgressBar.

Отображение полей сообщений

Чтобы отобразить окно сообщения с кнопками или значками, используйте операторы OR для добавления INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING или INSTALLMESSAGE_USER с параметрами окна сообщений, используемыми MessageBox и MessageBoxEx. Доступные параметры нажатия кнопки: MB_OK, MB_OKCANCEL, MB_ABORTRETRYIGNORE, MB_YESNOCANCEL, MB_YESNO и MB_RETRYCANCEL. Доступные параметры кнопки по умолчанию: MB_DEFBUTTON1, MB_DEFBUTTON2 и MB_DEFBUTTON3. Доступные параметры значков: MB_ICONERROR, MB_ICONQUESTION, MB_ICONWARNING и MB_ICONINFORMATION. Если параметры значка не указаны, установщик Windows выбирает стиль значка по умолчанию в зависимости от типа сообщения.

Например, следующий вызов MsiProcessMessage отправляет сообщение INSTALLMESSAGE_ERROR со значком MB_ICONWARNING и кнопками MB_ABORTRETRYCANCEL.

PMSIHANDLE hInstall;
PMSIHANDLE hRec;
MsiProcessMessage(hInstall, 
                  INSTALLMESSAGE(INSTALLMESSAGE_ERROR|MB_ABORTRETRYIGNORE|MB_ICONWARNING),
                  hRec);

Если пользовательское действие вызывает MsiProcessMessage, настраиваемое действие должно обрабатывать отмену пользователем и возвращать ERROR_INSTALL_USEREXIT.

Дополнительные сведения об отправке сообщений с помощью MsiProcessMessage см. в разделе Отправка сообщений в установщик Windows с помощью MsiProcessMessage.

Требования

Требование	Значение
Минимальная версия клиента	Установщик 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 в Windows Server 2003 или Windows XP
Целевая платформа	Windows
Header	msiquery.h
Библиотека	Msi.lib
DLL	Msi.dll

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

Функции действий установщика

Отправка сообщений в установщик Windows с помощью MsiProcessMessage

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