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

Статья
11/20/2024

Функция msiEnumComponentsEx перечисляет установленные компоненты 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

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

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

Примечание

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

[in] dwContext

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

Флаг	Значение
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

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

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

[out, optional] szSid

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

Длина буфера в этом расположении должна быть достаточно большой, чтобы содержать строковое значение, завершающее значение NULL, содержащее идентификатор БЕЗОПАСНОСТИ. Если буфер слишком мал, функция возвращает ERROR_MORE_DATA и расположение, на которое указывает pcchSid получает количество TCHAR в идентификаторе БЕЗОПАСНОСТИ, а не в том числе завершающий символ 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 NULL, функция возвращает ERROR_SUCCESS, если идентификатор безопасности существует, без получения значения 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 или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Установщик Windows 5.0 в Windows Server 2012, Windows 8, Windows Server 2008 R2 или Windows 7. Сведения о минимальном пакете обновления Windows, требуемом версией установщика Windows, см. в разделе "Требования к установщику Windows Run-Time".
целевая платформа	Виндоус
заголовка	msi.h
библиотеки	Msi.lib
DLL	Msi.dll

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