MsiEnumProductsExA 函式 (msi.h)

  • 發行項

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 要列舉之產品的 GUID。 只會列舉 szUserSid 和 dwContext 參數所指定內容範圍內的產品實例。 此參數可以設定為 NULL ，以列舉指定內容中的所有產品。

[in] szUserSid

以 Null 終止的字串，指定安全性識別碼 (SID) ，以限制列舉的內容。 特殊 SID 字串 s-1-1-0 (Everyone) 會指定系統中所有使用者的列舉。 s-1-1-0 以外的 SID 值會被視為 user-SID，並將列舉限制為目前使用者或系統中的任何使用者。 此參數可以設定為 NULL ，以將列舉範圍限製為目前使用者。

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

[in] dwContext

將列舉限制為內容。 此參數可以是下表所示之值的任一或組合。

Context 意義
MSIINSTALLCONTEXT_USERMANAGED
 列舉延伸至 szUserSid 所指定之使用者的所有使用者管理安裝。 無效的 SID 不會傳回任何專案。
MSIINSTALLCONTEXT_USERUNMANAGED
 列舉延伸至 szUserSid 所指定使用者的所有個別使用者-Unmanaged 安裝。 無效的 SID 不會傳回任何專案。
MSIINSTALLCONTEXT_MACHINE
 列舉延伸至所有每部計算機安裝。 當 dwInstallContext 設定為僅MSIINSTALLCONTEXT_MACHINE時， szUserSID 參數必須是 NULL。

[in] dwIndex

指定要擷取的產品索引。 第一次呼叫 MsiEnumProductsEx 函式時，此參數必須是零，然後針對後續呼叫遞增。 只有在先前的呼叫傳回ERROR_SUCCESS時，才應該遞增索引。 因為產品未訂購，所以任何新產品都有任意索引。 這表示函式可以依任何順序傳回產品。

[out, optional] szInstalledProductCode

TCHAR 的 Null 終止字串，可提供所列舉產品實例的 ProductCode GUID。 此參數可以是 Null。

[out, optional] pdwInstalledContext

傳回要列舉之產品實例的內容。 輸出值可以是MSIINSTALLCONTEXT_USERMANAGED、MSIINSTALLCONTEXT_USERUNMANAGED或MSIINSTALLCONTEXT_MACHINE。 此參數可以是 Null。

[out, optional] szSid

輸出緩衝區，接收此產品實例所在的帳戶字串SID。 這個緩衝區會針對安裝在每部計算機內容中的實例傳回空字串。

此緩衝區應該夠大，足以包含 SID。 如果緩衝區太小，則函式會傳回ERROR_MORE_DATA，並將 *pcchSid 設定為 SID 中的 TCHAR 數目，不包括終止的 NULL 字元。

如果 szSid 設定為 NULL ， 且 pcchSid 設定為有效的指標，則函式會傳回ERROR_SUCCESS，並將 *pcchSid 設定為值中的 TCHAR 數目，不包括終止 的 NULL。 然後可以再次呼叫 函式以擷取值，而 szSid 緩衝區夠大，足以包含 *pcchSid + 1 個字元。

如果 szSid 和 pcchSid 都設定為 NULL，則函式會傳回ERROR_SUCCESS值，而不會擷取值。

[in, out, optional] pcchSid

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

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

傳回值

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

傳回碼 Description
ERROR_ACCESS_DENIED
 如果範圍包含目前使用者以外的使用者，您需要系統管理員許可權。
ERROR_BAD_CONFIGURATION
 組態數據已損毀。
ERROR_INVALID_PARAMETER
 無效的參數已傳遞至 函式。
ERROR_NO_MORE_ITEMS
 沒有其他要列舉的產品。
ERROR_SUCCESS
 列舉產品。
ERROR_MORE_DATA
 szSid 參數太小，無法取得使用者 SID。
ERROR_UNKNOWN_PRODUCT
 產品不會安裝在指定內容中的電腦上。
ERROR_FUNCTION_FAILED
 非預期的內部失敗。

備註

若要列舉產品，應用程式一開始必須呼叫 MsiEnumProductsEx 函式， 並將 iIndex 參數設定為零。 然後，應用程式必須遞增 iProductIndex 參數並呼叫 MsiEnumProductsEx ，直到傳回 ERROR_NO_MORE_ITEMS ，而且沒有其他要列舉的產品。

對 MsiEnumProductsEx 進行多個呼叫以列舉所有產品時，每個呼叫都必須從相同的線程進行。

用戶必須具有系統管理員許可權，才能列舉目前用戶帳戶以外的所有用戶帳戶或使用者帳戶的產品。 列舉會略過只公告 (的產品，例如未在每位使用者非受控內容中安裝的產品) 。

使用 MsiGetProductInfoEx 取得 MsiEnumProductsEx 列舉之每個產品實例的狀態或其他資訊。

注意

msi.h 標頭會將 MsiEnumProductsEx 定義為別名，根據 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 Server 2003 或 Windows XP 上的 Windows Installer 3.0 或更新版本。 如需 Windows Installer 版本所需的最低 Windows Service Pack 相關信息，請參閱 Windows Installer Run-Time 需求。
目標平台 Windows
標頭 msi.h
程式庫 Msi.lib
Dll Msi.dll

另請參閱

MsiEnumProducts

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

ProductCode

拿掉修補程式