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

Статья
11/20/2024

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

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

Синтаксис

UINT MsiEnumClientsExA(
  [in]                LPCSTR            szComponent,
  [in, optional]      LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwProductIndex,
  [out, optional]     CHAR [39]         szProductBuf,
  [out, optional]     MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional]     LPSTR             szSid,
  [in, out, optional] LPDWORD           pcchSid
);

Параметры

[in] szComponent

GUID кода компонента, определяющий компонент. Функция перечисляет приложения, использующие этот компонент.

[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	Указывает перечисление для всех пользователей в системе.

Примечание Нельзя использовать специальную строку SID 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] dwProductIndex

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

[out, optional] szProductBuf

Строковое значение, которое получает код продукта для приложения. Длина буфера в этом расположении должна быть достаточно большой, чтобы содержать строковое значение, завершающее значение 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, optional] pcchSid

Указатель на расположение в памяти, содержащее переменную, указывающую количество TCHAR в идентификаторе безопасности, не включая завершающийся символ NULL. Когда функция возвращается, эта переменная имеет размер запрошенного идентификатора БЕЗОПАСНОСТИ, может ли функция успешно скопировать идентификатор безопасности и завершить значение NULL в расположение буфера, на которое указывает szSid. Размер возвращается в виде числа TCHAR в запрошенном значении, а не включая завершающийся пустой символ.

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

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

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

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

Замечания

Заметка

Заголовок msi.h определяет MsiEnumClientsEx как псевдоним, который автоматически выбирает версию 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

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