共用方式為


msiEnumClientsExA 函式 (msi.h)

MsiEnumClientsEx函式會列舉使用指定元件之已安裝的應用程式。 函式會在每次呼叫應用程式時擷取應用程式的 產品代碼

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

語法

UINT MsiEnumClientsExA(
  [in]                LPCSTR            szComponent,
  [in, optional]      LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwProductIndex,
  [out, optional]     CHAR [39]         szProductBuf,
  [out, optional]     MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional]     LPSTR             szSid,
  [in, out, optional] LPDWORD           pcchSid
);

參數

[in] szComponent

識別元件的元件程式碼 GUID。 函式會列舉使用此元件的應用程式。

[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所識別使用者所安裝之應用程式的實例。

這可以是下列值的組合。

Context 意義
MSIINSTALLCONTEXT_USERMANAGED
1
包含安裝在個別使用者管理安裝內容中的應用程式。
MSIINSTALLCONTEXT_USERUNMANAGED
2
包含安裝在個別使用者-Unmanaged 安裝內容中的應用程式。
MSIINSTALLCONTEXT_MACHINE
4
包含安裝在每部電腦安裝內容中的應用程式。 當 dwInstallCoNtext 設定為 僅MSIINSTALLCONTEXT_MACHINE 時, szUserSID 參數的值必須是 Null

[in] dwProductIndex

指定要擷取之應用程式的索引。 此參數的值必須在第一次呼叫函式時 (0) 為零。 針對每個後續呼叫,索引必須遞增 1。 只有在前一次呼叫函式傳回 ERROR_SUCCESS時,才會遞增索引。

[out, optional] szProductBuf

字串值,可接收應用程式的產品代碼。 這個位置的緩衝區長度應該夠大,足以保存包含產品代碼的 Null 終止字串值。 前 38 個 TCHAR 字元會接收元件的 GUID,而第 39 個字元會收到終止的 Null 字元。

[out, optional] pdwInstalledContext

旗標,提供應用程式的安裝內容。

這可以是下列值的組合。

Context 意義
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, optional] pcchSid

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

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

傳回值

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

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

備註

注意

msi.h 標頭會根據 UNICODE 預處理器常數的定義,將 MsiEnumClientsEx 定義為別名,自動選取此函式的 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