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

Статья
08/24/2023

Функция MsiEnumProductsEx перечисляет один или все экземпляры продуктов, которые в настоящее время объявлены или установлены в указанных контекстах. Эта функция заменяет MsiEnumProducts.

Синтаксис

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

Параметры

[in, optional] szProductCode

Идентификатор ProductCode для перечисления продукта. Перечисляются только экземпляры продуктов в пределах контекста, указанного szUserSid, и параметры dwCon text dwContext. Этот параметр можно задать для null для перечисления всех продуктов в указанном контексте.

[in] szUserSid

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

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

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

[in] dwContext

Ограничивает перечисление контекстом. Этот параметр может быть любым или сочетанием значений, показанных в следующей таблице.

Контекст	Значение
MSIINSTALLCONTEXT_USERMANAGED	Перечисление распространяется на все управляемые пользователем установки для пользователей, указанных szUserSid. Недопустимый идентификатор БЕЗОПАСНОСТИ не возвращает элементы.
MSIINSTALLCONTEXT_USERUNMANAGED	Перечисление распространяется на все неуправляемые установки для пользователей, указанных szUserSid. Недопустимый идентификатор БЕЗОПАСНОСТИ не возвращает элементы.
MSIINSTALLCONTEXT_MACHINE	Перечисление распространяется на все установки на компьютер. Если dwInstallContext задано только MSIINSTALLCONTEXT_MACHINE, параметр szUserSID должен быть NULL.

[in] dwIndex

Указывает индекс извлекаемого продукта. Этот параметр должен быть равен нулю для первого вызова функции MsiEnumProductsEx, а затем увеличивается для последующих вызовов. Индекс следует увеличить, только если предыдущий вызов вернул ERROR_SUCCESS. Поскольку продукты не упорядочены, любой новый продукт имеет произвольный индекс. Это означает, что функция может возвращать продукты в любом порядке.

[out, optional] szInstalledProductCode

Строка, завершающаяся значением NULL, TCHAR , которая предоставляет guid ProductCode перечисленного экземпляра продукта. Этот параметр может быть NULL.

[out, optional] pdwInstalledContext

Возвращает контекст перечисленного экземпляра продукта. Выходное значение может быть MSIINSTALLCONTEXT_USERMANAGED, MSIINSTALLCONTEXT_USERUNMANAGED или MSIINSTALLCONTEXT_MACHINE. Этот параметр может быть NULL.

[out, optional] szSid

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

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

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

Если szSid и pcchSid задано значение null NULL, функция возвращает ERROR_SUCCESS, если значение существует, не извлекая значение.

[in, out, optional] pcchSid

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

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

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

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

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

Замечания

Чтобы перечислить продукты, приложение должно изначально вызвать функцию MsiEnumProductsEx с параметром iIndex равным нулю. Затем приложение должно увеличить параметр iProductIndex и вызвать MsiEnumProductsEx, пока он не вернет ERROR_NO_MORE_ITEMS и нет никаких продуктов для перечисления.

При выполнении нескольких вызовов MsiEnumProductsEx для перечисления всех продуктов каждый вызов должен выполняться из одного потока.

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

Используйте MsiGetProductInfoEx для получения состояния или других сведений о каждом экземпляре продукта, перечисленном MsiEnumProductsEx.

Заметка

Заголовок msi.h определяет MsiEnumProductsEx как псевдоним, который автоматически выбирает версию 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 3.0 или более поздней версии в Windows Server 2003 или Windows XP. Сведения о минимальном пакете обновления Windows, требуемом версией установщика Windows, см. в разделе "Требования к установщику Windows Run-Time".
целевая платформа	Виндоус
заголовка	msi.h
библиотеки	Msi.lib
DLL	Msi.dll

См. также

MsiEnumProducts

не поддерживается в установщике Windows 2.0 и более ранних

ProductCode

удаление исправлений

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