Функция MsiEnumComponentsExA (msi.h)

  • Статья

Функция MsiEnumComponentsEx перечисляет установленные компоненты. Функция получает код компонента для одного компонента при каждом вызове. Код компонента — это идентификатор GUID строки, уникальный для компонента, версии и языка.

Установщик Windows 4.5 или более ранней версии: Не поддерживается. Эта функция доступна начиная с установщика Windows 5.0.

Синтаксис

UINT MsiEnumComponentsExA(
  [in, optional]  LPCSTR            szUserSid,
  [in]            DWORD             dwContext,
  [in]            DWORD             dwIndex,
  [out, optional] CHAR [39]         szInstalledComponentCode,
  [out, optional] MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional] LPSTR             szSid,
  [in, out]       LPDWORD           pcchSid
);

Параметры

[in, optional] szUserSid

Строка, завершающаяся нулевым значением, которая содержит идентификатор безопасности (SID). Перечисление установленных компонентов распространяется на пользователей, определенных по этому идентификатору безопасности. Специальная строка sid s-1-1-0 (Все) указывает перечисление всех установленных компонентов во всех продуктах всех пользователей в системе. Значение SID, отличное от s-1-1-0, указывает идентификатор безопасности пользователя для конкретного пользователя и ограничивает перечисление экземплярами приложений, установленных указанным пользователем.

Тип SID Значение
NULL
 Указывает текущего пользователя, вошедшего в систему.
Идентификатор безопасности пользователя
 Перечисление для определенного пользователя в системе. Пример идентификатора безопасности пользователя — "S-1-3-64-2415071341-1358098788-3127455600-2561".
s-1-1-0
 Указывает всех пользователей в системе.
 
Примечание  

Специальная строка sid s-1-5-18 (System) не может использоваться для перечисления приложений, установленных в контексте установки для каждого компьютера. При установке значения SID s-1-5-18 возвращается ERROR_INVALID_PARAMETER. Если параметру dwContext присвоено значение только MSIINSTALLCONTEXT_MACHINE, значение szUserSid должно иметь значение NULL.

 

[in] dwContext

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

Flag Значение
MSIINSTALLCONTEXT_USERMANAGED
1
 Включите продукты, которые существуют в контексте управляемой установки для каждого пользователя.
MSIINSTALLCONTEXT_USERUNMANAGED
2
 Включите продукты, существующие в контексте неуправляемой установки для каждого пользователя.
MSIINSTALLCONTEXT_MACHINE
4
 Включите продукты, существующие в контексте установки для каждого компьютера. Если параметру dwInstallContext присвоено значение только MSIINSTALLCONTEXT_MACHINE, параметр szUserSID должен иметь значение NULL.

[in] dwIndex

Указывает индекс извлекаемого компонента. Этот параметр должен иметь значение ноль (0) для первого вызова функции MsiEnumComponentsEx . Для каждого последующего вызова индекс должен увеличиваться на 1. Индекс следует увеличивать только в том случае, если предыдущий вызов функции возвращает ERROR_SUCCESS. Компоненты не упорядочены и могут быть возвращены функцией в любом порядке.

[out, optional] szInstalledComponentCode

Выходной буфер, который получает GUID кода компонента для установленного компонента. Длина буфера должна быть достаточно большой, чтобы вместить строковое значение, завершающееся значением NULL, содержащее код компонента. Первые 38 символов TCHAR получают GUID для компонента, а 39-й — завершающий символ NULL.

[out, optional] pdwInstalledContext

Флаг, предоставляющий контекст установки приложению, которое установило компонент.

Flag Значение
MSIINSTALLCONTEXT_USERMANAGED
1
 Приложение устанавливается в контексте управляемой установки для каждого пользователя.
MSIINSTALLCONTEXT_USERUNMANAGED
2
 Приложение устанавливается в контексте неуправляемой установки для каждого пользователя.
MSIINSTALLCONTEXT_MACHINE
4
 Приложение устанавливается в контексте установки для каждого компьютера.

[out, optional] szSid

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

Длина буфера в этом расположении должна быть достаточно большой, чтобы вместить строковое значение, завершающееся значением NULL, содержащее идентификатор безопасности. Если буфер слишком мал, функция возвращает ERROR_MORE_DATA и расположение, на которое указывает pcchSid , получает число TCHAR в sid, не включая завершающий символ NULL.

Если для szSid задано значение NULL , а pcchSid является допустимым указателем на расположение в памяти, функция возвращает ERROR_SUCCESS и расположение получает число TCHAR в идентификаторе безопасности, не включая завершающий символ NULL. Затем функцию можно вызвать снова, чтобы получить значение, при этом размер буфера szSid достаточно велик, чтобы содержать *pcchSid + 1 символов.

Тип SID Значение
Пустая строка.
 Приложение устанавливается в контексте установки для каждого компьютера.
Идентификатор безопасности пользователя
 Идентификатор безопасности для пользователя в системе, которая установила приложение.

[in, out] pcchSid

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

Для этого параметра можно задать значение NULL , только если szSid также имеет значение NULL, в противном случае функция возвращает ERROR_INVALID_PARAMETER. Если оба значения szSid и pcchSid имеют значение NULL, функция возвращает ERROR_SUCCESS , если sid существует, без получения значения SID.

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

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

Код возврата Описание
ERROR_ACCESS_DENIED
 Для перечисления компонентов приложений, установленных другими пользователями, кроме текущего пользователя, требуются права администратора.
ERROR_BAD_CONFIGURATION
 Данные конфигурации повреждены.
ERROR_INVALID_PARAMETER
 В функцию передается недопустимый параметр.
ERROR_NO_MORE_ITEMS
 Нет дополнительных компонентов для перечисления.
ERROR_SUCCESS
 Функция выполнена успешно.
ERROR_MORE_DATA
 Предоставленный буфер был слишком мал для хранения всего значения.
ERROR_FUNCTION_FAILED
 Сбой функции.

Комментарии

Примечание

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

Требования

Требование Значение
Минимальная версия клиента Установщик Windows 5.0 в Windows Server 2012, Windows 8, Windows Server 2008 R2 или Windows 7. Сведения о минимальном пакете обновления Windows, необходимом для версии установщика Windows, см. в статье Требования к установщику Windows Run-Time.
Целевая платформа Windows
Header msi.h
Библиотека Msi.lib
DLL Msi.dll