msiEnumPatchesExA 函式 (msi.h)

  • 發行項

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 結束的字串，指定列舉修補程式之產品的 ProductCode GUID。 如果為非 NULL，修補程式列舉僅限於 szUserSid 和 dwContext 所指定使用者和內容下此產品的實例。 如果 為 NULL，則會列舉指定內容下所有產品的修補程式。

[in, optional] szUserSid

以 Null 結尾的字串，指定限制列舉內容的安全性標識碼 (SID) 。 特殊 SID 字串 「S-1-1-0」 (Everyone) 會指定系統中所有使用者的列舉。 “S-1-1-0” 以外的 SID 值會被視為使用者 SID，並限制該使用者的列舉。 針對目前使用者以外的使用者列舉時，不會列舉使用小於 Windows Installer 3.0 版的版本，在每一使用者 Unmanaged 內容中套用的任何修補程式。 此參數可以設定為 NULL ，以指定目前的使用者。

SID 類型 意義
NULL
 指定目前登入的使用者。
使用者 SID
 系統中特定用戶的列舉。 使用者 SID 的範例是 “S-1-3-64-2415071341-1358098788-3127455600-2561”。
s-1-1-0
 系統中所有用戶的列舉。
 
注意 特殊的 SID 字串 「S-1-5-18」 (系統) 無法用來列舉依每部電腦安裝的產品或修補程式。 將 SID 值設定為 「S-1-5-18」 會 傳回ERROR_INVALID_PARAMETER。 當 dwContext 設定為 僅MSIINSTALLCONTEXT_MACHINE 時， szUserSid 必須是 NULL。
 

[in] dwContext

將列舉限制為一或一個內容組合。 這個參數可以是下列值的任何一個或組合。

Context 意義
MSIINSTALLCONTEXT_USERMANAGED
 針對 szUserSid 所指定的使用者，延伸至所有使用者管理的列舉。 無效的 SID 不會傳回任何專案。
MSIINSTALLCONTEXT_USERUNMANAGED
 在此內容中，只有與 Windows Installer 3.0 版一起安裝的修補程式會針對不是目前使用者的用戶列舉。 針對目前的使用者，函式會列舉所有已安裝和新修補程式。 szUserSid 的 SID 無效不會傳回任何專案。
MSIINSTALLCONTEXT_MACHINE
 擴充至所有每部計算機安裝的列舉。 當 dwContext 設定為 僅MSIINSTALLCONTEXT_MACHINE 時， szUserSid 參數必須是 NULL。

[in] dwFilter

列舉的篩選條件。 這個參數可以是下列參數的其中一個或組合。

篩選 意義
MSIPATCHSTATE_APPLIED
1
 列舉包含已套用的修補程式。 列舉不包含已取代或過時的修補程式。
MSIPATCHSTATE_SUPERSEDED
2
 列舉包含標示為已取代的修補程式。
MSIPATCHSTATE_OBSOLETED
4
 列舉包含標示為過時的修補程式。
MSIPATCHSTATE_REGISTERED
8
 列舉包含已註冊但尚未套用的修補程式。 MsiSourceListAddSourceEx 函式可以註冊新的修補程式。
注意 不會列舉為目前使用者以外的用戶註冊並套用至個別使用者 Unmanaged 內容中的修補程式。
 
MSIPATCHSTATE_ALL
15
 列舉包含所有已套用、過時、已取代和已註冊的修補程式。

[in] dwIndex

要擷取之修補程式的索引。 第一次呼叫 MsiEnumPatchesEx 函 式時，此參數必須為零，然後針對後續呼叫遞增。 只有當先前的呼叫傳回ERROR_SUCCESS時， dwIndex 參數才應該遞增。

[out, optional] szPatchCode

要包含所列舉修補程式 GUID 的輸出緩衝區。 緩衝區應該夠大，足以保存 GUID。 此參數可以是 Null。

[out, optional] szTargetProductCode

輸出緩衝區，包含接收此修補程式之產品的 ProductCode GUID。 緩衝區應該夠大，足以保存 GUID。 此參數可以是 Null。

[out, optional] pdwTargetProductContext

傳回要列舉之修補程序的內容。 輸出值可以是 MSIINSTALLCONTEXT_USERMANAGED、 MSIINSTALLCONTEXT_USERUNMANAGED或 MSIINSTALLCONTEXT_MACHINE。 此參數可以是 Null。

[out, optional] szTargetUserSid

輸出緩衝區，接收此修補程序實例所在帳戶的字串 SID。 此緩衝區會針對每部計算機內容傳回空字串。

這個緩衝區應該夠大，足以包含 SID。 如果緩衝區太小，函式會 傳回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

指定 szTargetUserSid 緩衝區中 TCHAR 數目的變數指標。 當函式傳回時，不論函式是否將值複製到指定的緩衝區，此參數會設定為要求值的大小。 大小會以要求值中的 TCHAR 數目傳回，不包括終止的 Null 字元。

只有當 szTargetUserSid 也是 NULL 時，此參數才能設定為 NULL，否則函式會傳回ERROR_INVALID_PARAMETER。

傳回值

MsiEnumPatchesEx 函式會傳回下列其中一個值。

傳回碼 Description
ERROR_ACCESS_DENIED
 函式嘗試存取許可權不足的資源失敗。
ERROR_BAD_CONFIGURATION
 設定數據已損毀。
ERROR_INVALID_PARAMETER
 無效的參數會傳遞至 函式。
ERROR_NO_MORE_ITEMS
 沒有其他要列舉的修補程式。
ERROR_SUCCESS
 已成功列舉修補程式。
ERROR_UNKNOWN_PRODUCT
 szProduct 指定的產品未安裝在指定內容中的電腦上。
ERROR_MORE_DATA
 當 pcchTargetUserSid 指向小於複製SID所需的緩衝區大小時，就會傳回這個值。 在此情況下，使用者可以修正緩衝區，並針對相同的索引值再次呼叫 MsiEnumPatchesEx 。

備註

非系統管理員只能列舉其可見度內的修補程式。 系統管理員可以列舉其他用戶內容的修補程式。

注意

msi.h 標頭會將 MsiEnumPatchesEx 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

需求 值
最低支援的用戶端 Windows Server 2012、Windows 8、Windows Server 2008 R2 或 Windows 7 上的 Windows Installer 5.0。 Windows Server 2008 或 Windows Vista 上的 Windows Installer 4.0 或 Windows Installer 4.5。 如需 Windows Installer 版本所需的最低 Windows Service Pack 相關信息，請參閱 Windows Installer Run-Time 需求。
目標平台 Windows
標頭 msi.h
程式庫 Msi.lib
Dll Msi.dll

另請參閱

安裝內容

MsiSourceListAddSourceEx

Windows Installer 2.0 和更早版本中不支援

ProductCode