共用方式為

msiEnumComponentsExA 函式 (msi.h)

  • 發行項

MsiEnumComponentsEx 函式會列舉已安裝的元件。 函式會在每次呼叫元件時擷取一個元件的元件程式代碼。 元件程式代碼是元件、版本和語言唯一的字串 GUID。

Windows Installer 4.5 或更早版本： 不支援。 此函式從 Windows Installer 5.0 開始提供。

語法

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

參數

[in, optional] szUserSid

以 Null 結尾的字串，其中包含安全性識別碼 (SID.) 已安裝元件的列舉會延伸至此 SID 所識別的使用者。 特殊 SID 字串 s-1-1-0 (Everyone) 會指定系統中所有使用者所有產品上所有已安裝元件的列舉。 s-1-1-0 以外的 SID 值會指定特定使用者的 SID，並將列舉限制為指定使用者所安裝之應用程式的實例。

SID 類型 意義
NULL
 指定目前登入的使用者。
使用者 SID
 系統中特定用戶的列舉。 使用者 SID 的範例是 “S-1-3-64-2415071341-1358098788-3127455600-2561”。
s-1-1-0
 指定系統中的所有使用者。
 
注意  

特殊 SID 字串 s-1-5-18 (System) 無法用來列舉安裝在每部電腦安裝內容中的應用程式。 將 SID 值設定為 s-1-5-18 會傳回ERROR_INVALID_PARAMETER。 當 dwContext 設定為僅MSIINSTALLCONTEXT_MACHINE時， szUserSid 必須是 NULL。

 

[in] dwContext

旗標，將已安裝元件的列舉限制為在指定安裝內容中安裝的產品實例。 列舉只包含 szUserSid 所指定使用者所安裝的產品實例。

旗標 意義
MSIINSTALLCONTEXT_USERMANAGED
1
 包含存在於個別使用者管理安裝內容中的產品。
MSIINSTALLCONTEXT_USERUNMANAGED
2
 包含存在於個別使用者-Unmanaged 安裝內容中的產品。
MSIINSTALLCONTEXT_MACHINE
4
 包含存在於每部計算機安裝內容中的產品。 當 dwInstallContext 設定為僅MSIINSTALLCONTEXT_MACHINE時， szUserSID 參數必須是 NULL。

[in] dwIndex

指定要擷取之元件的索引。 此參數必須是 0 (0) ，才能第一次呼叫 MsiEnumComponentsEx 函式。 針對每個後續呼叫，索引必須遞增 1。 只有在前一次呼叫函式傳回ERROR_SUCCESS時，才應該遞增索引。 元件不會排序，而且可以依任何順序由函式傳回。

[out, optional] szInstalledComponentCode

輸出緩衝區，接收已安裝元件的元件程式代碼 GUID。 緩衝區的長度應該夠大，足以保存包含元件程式代碼的 Null 終止字串值。 前 38 個 TCHAR 字元會接收元件的 GUID，而第 39 個字元會收到終止的 NULL 字元。

[out, optional] pdwInstalledContext

旗標，提供安裝內容的應用程式安裝元件。

旗標 意義
MSIINSTALLCONTEXT_USERMANAGED
1
 應用程式會安裝在每個使用者管理的安裝內容中。
MSIINSTALLCONTEXT_USERUNMANAGED
2
 應用程式會安裝在每位使用者-Unmanaged 安裝內容中。
MSIINSTALLCONTEXT_MACHINE
4
 應用程式會安裝在每部電腦安裝安裝內容中。

[out, optional] szSid

接收安全性標識碼 (SID) ，識別已安裝擁有元件之應用程式的使用者。 如果應用程式實例安裝在每部電腦安裝內容中，此位置就會收到空字串。

這個位置的緩衝區長度應該夠大，足以保存包含 SID 的 Null 終止字串值。 如果緩衝區太小，函式會傳回 ERROR_MORE_DATA ， 而pcchSid 所指向的位置會接收SID中的 TCHAR 數目，不包括終止的NULL字元。

如果 szSid 設定為 NULL ， 而 pcchSid 是記憶體中位置的有效指標，則函式會傳回 ERROR_SUCCESS ，而且該位置會接收 SID 中的 TCHAR 數目，不包括終止的 Null 字元。 然後，您可以再次呼叫 函式以擷取值，而 szSid 緩衝區的大小夠大，足以包含 *pcchSid + 1 個字元。

SID 類型 意義
空字串
 應用程式會安裝在每部電腦安裝內容中。
使用者 SID
 安裝應用程式的系統中使用者的 SID。

[in, out] pcchSid

接收 SID 中的 TCHAR 數目，不包括終止的 Null 字元。 當函式傳回時，此變數會設定為要求 SID 的大小，不論函式是否可以成功複製 SID，並將 Null 字元終止至 szSid 所指向的緩衝區位置。 大小會以要求值中的 TCHAR 數目傳回，不包括終止 Null 字元。

只有當 szSid 也是 NULL 時，此參數才能設定為 NULL，否則函式會傳回ERROR_INVALID_PARAMETER。 如果 szSid 和 pcchSid 都設定為 NULL，則函式會傳回 ERROR_SUCCESS 如果 SID 存在，而不需要擷取 SID 值。

傳回值

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

傳回碼 Description
ERROR_ACCESS_DENIED
 需要系統管理員許可權，才能列舉目前使用者以外的使用者所安裝之應用程式的元件。
ERROR_BAD_CONFIGURATION
 組態數據已損毀。
ERROR_INVALID_PARAMETER
 無效的參數會傳遞至 函式。
ERROR_NO_MORE_ITEMS
 沒有其他要列舉的元件。
ERROR_SUCCESS
 此函數已成功。
ERROR_MORE_DATA
 提供的緩衝區太小，無法保存整個值。
ERROR_FUNCTION_FAILED
 函式失敗。

備註

注意

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

規格需求

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