Функция 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

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

[in, optional] szUserSid

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

Тип 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

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

Контекст	Значение
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".
целевая платформа	Виндоус
заголовка	msi.h
библиотеки	Msi.lib
DLL	Msi.dll

См. также

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

MsiSourceListAddSourceEx

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

ProductCode

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