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

Статья
03/15/2023

Функция MsiEnumPatchesEx перечисляет все исправления в определенном контексте или во всех контекстах. Исправления, уже примененные к продуктам, перечисляются. Также перечисляются исправления, которые были зарегистрированы, но еще не применены к продуктам.

Синтаксис

UINT MsiEnumPatchesExA(
  [in, optional]      LPCSTR            szProductCode,
  [in, optional]      LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwFilter,
  [in]                DWORD             dwIndex,
  [out, optional]     CHAR [39]         szPatchCode,
  [out, optional]     CHAR [39]         szTargetProductCode,
  [out, optional]     MSIINSTALLCONTEXT *pdwTargetProductContext,
  [out, optional]     LPSTR             szTargetUserSid,
  [in, out, optional] LPDWORD           pcchTargetUserSid
);

Параметры

[in, optional] szProductCode

Строка с пустым завершением, указывающая GUID ProductCode продукта, для которого перечислены исправления. Если значение не равно NULL, перечисление исправлений ограничивается экземплярами этого продукта в пользовательском и контексте, заданных szUserSid и dwContext. Если значение РАВНО NULL, исправления для всех продуктов в указанном контексте перечисляются.

[in, optional] szUserSid

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

Тип идентификатора безопасности	Значение
NULL	Указывает пользователя, выполнившего вход в текущий момент.
Идентификатор безопасности пользователя	Перечисление для определенного пользователя в системе. Пример идентификатора безопасности пользователя — "S-1-3-64-2415071341-1358098788-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

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

Контекст	Значение
MSIINSTALLCONTEXT_USERMANAGED	Перечисление, которое распространяется на все управляемые пользователем установки для пользователей, которые указывает szUserSid . Недопустимый идентификатор безопасности не возвращает элементов.
MSIINSTALLCONTEXT_USERUNMANAGED	В этом контексте перечислены только исправления, установленные с установщиком Windows версии 3.0, для пользователей, которые не являются текущим пользователем. Для текущего пользователя функция перечисляет все установленные и новые исправления. Недопустимый идентификатор безопасности для szUserSid не возвращает элементов.
MSIINSTALLCONTEXT_MACHINE	Перечисление, которое распространяется на все установки на компьютере. Если параметру dwContext присвоено значение только MSIINSTALLCONTEXT_MACHINE , параметр szUserSid должен иметь значение NULL.

[in] dwFilter

Фильтр для перечисления. Этот параметр может быть одним или сочетанием следующих параметров.

Фильтр	Значение
MSIPATCHSTATE_APPLIED 1	Перечисление включает исправления, которые были применены. Перечисление не включает заменяемые или устаревшие исправления.
MSIPATCHSTATE_SUPERSEDED 2	Перечисление включает исправления, помеченные как замененные.
MSIPATCHSTATE_OBSOLETED 4	Перечисление включает исправления, помеченные как устаревшие.
MSIPATCHSTATE_REGISTERED 8	Перечисление включает исправления, которые зарегистрированы, но еще не применены. Функция MsiSourceListAddSourceEx может регистрировать новые исправления. Примечание Исправления, зарегистрированные для пользователей, отличных от текущего пользователя, и примененные в контексте для отдельных пользователей, не перечисляются.
MSIPATCHSTATE_ALL 15	Перечисление включает все примененные, устаревшие, замененные и зарегистрированные исправления.

[in] dwIndex

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

[out, optional] szPatchCode

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

[out, optional] szTargetProductCode

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

[out, optional] pdwTargetProductContext

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

[out, optional] szTargetUserSid

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

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

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

Если szTargetUserSid и pcchTargetUserSid имеют значение NULL, функция возвращает ERROR_SUCCESS , если значение существует, без получения значения.

[in, out, optional] pcchTargetUserSid

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

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

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

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

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

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

Примечание

Заголовок msi.h определяет MsiEnumPatchesEx в качестве псевдонима, который автоматически выбирает версию 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, необходимом для версии установщика Windows, см. в разделе Требования к установщику Windows Run-Time.
Целевая платформа	Windows
Header	msi.h
Библиотека	Msi.lib
DLL	Msi.dll

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

Контекст установки

MsiSourceListAddSourceEx

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

ProductCode

Share via