MsiEnumProductsExA 関数 (msi.h)

  • [アーティクル]

MsiEnumProductsEx 関数は、指定されたコンテキストで現在アドバタイズまたはインストールされている製品の 1 つまたはすべてのインスタンスを列挙します。 この関数は 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

列挙のコンテキストを制限するセキュリティ識別子 (SID) を指定する Null で終わる文字列。 特殊な SID 文字列 s-1-1-0 (Everyone) は、システム内のすべてのユーザーの列挙を指定します。 s-1-1-0 以外の SID 値はユーザー SID と見なされ、列挙は現在のユーザーまたはシステム内の任意のユーザーに制限されます。 列挙スコープを現在のユーザーに制限するには、このパラメーターを NULL に設定できます。

SID の種類 意味
NULL
 現在ログオンしているユーザーを指定します。
ユーザー SID
 システム内の特定のユーザーの列挙を指定します。 ユーザー SID の例としては、"S-1-3-64-2415071341-1358098788-3127455600-2561" があります。
s-1-1-0
 システム内のすべてのユーザーの列挙を指定します。
 
メモ 特殊な SID 文字列 s-1-5-18 (システム) を使用して、コンピューターごとにインストールされている製品またはパッチを列挙することはできません。 dwContext が MSIINSTALLCONTEXT_MACHINE のみに設定されている場合、szUserSid は NULL である必要があります。
 

[in] dwContext

列挙をコンテキストに制限します。 このパラメーターには、次の表に示す値の任意の 1 つまたは組み合わせを指定できます。

Context 意味
MSIINSTALLCONTEXT_USERMANAGED
 szUserSid で指定されたユーザーのすべてのユーザー管理インストールに拡張された列挙。 無効な SID は項目を返しません。
MSIINSTALLCONTEXT_USERUNMANAGED
 szUserSid で指定されたユーザーのすべてのユーザー非管理対象インストールに拡張された列挙。 無効な SID は項目を返しません。
MSIINSTALLCONTEXT_MACHINE
 列挙は、すべてのマシンごとのインストールに拡張されます。 dwInstallContext がMSIINSTALLCONTEXT_MACHINEのみに設定されている場合、szUserSID パラメーターは NULL である必要があります。

[in] dwIndex

取得する製品のインデックスを指定します。 このパラメーターは、 MsiEnumProductsEx 関数の最初の呼び出しでは 0 にし、その後の呼び出しではインクリメントする必要があります。 前の呼び出しがERROR_SUCCESSを返した場合にのみ、インデックスをインクリメントする必要があります。 製品は順序付けされていないので、新しい製品には任意のインデックスが付けられます。 つまり、関数は任意の順序で製品を返すことができます。

[out, optional] szInstalledProductCode

列挙される製品インスタンスの ProductCode GUID を提供する TCHAR の Null で終わる文字列。 このパラメーターは、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 を終了する NULL を含まない値の TCHAR の数に設定します。 関数を再度呼び出して値を取得し、 *pcchSid + 1 文字を格納するのに十分な大きさの szSid バッファーを使用できます。

szSid と pcchSid の両方が NULL に設定されている場合、値が存在する場合、関数は値を取得せずにERROR_SUCCESSを返します。

[in, out, optional] pcchSid

関数を呼び出すとき、このパラメーターは、szSid バッファー内の TCHAR の数を指定する変数へのポインターである必要があります。 関数が戻るときに、関数が指定したバッファーに値をコピーするかどうかに関係なく、このパラメーターは要求された値のサイズに設定されます。 サイズは、要求された値の TCHAR の数として返されます。終端の null 文字は含まれません。

このパラメーターは、szSid も NULL の場合にのみ NULL に設定できます。それ以外の場合、関数はERROR_INVALID_PARAMETERを返します。

戻り値

MsiEnumProductsEx 関数は、次のいずれかの値を返します。

リターン コード 説明
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
 予期しない内部エラー。

注釈

製品を列挙するには、iIndex パラメーターを 0 に設定して、アプリケーションで最初に MsiEnumProductsEx 関数を呼び出す必要があります。 その後、アプリケーションは iProductIndex パラメーターをインクリメントし、ERROR_NO_MORE_ITEMSを返し、列挙する製品がなくなったら MsiEnumProductsEx を呼び出す必要があります。

すべての製品を列挙するために MsiEnumProductsEx に対して複数の呼び出しを行う場合、各呼び出しは同じスレッドから行う必要があります。

ユーザーには、すべてのユーザー アカウントまたは現在のユーザー アカウント以外のユーザー アカウント全体で製品を列挙するための管理者権限が必要です。 列挙は、すべてのユーザーまたは現在のユーザー以外のユーザーを列挙するときに、ユーザーごとのアンマネージド コンテキストでのみアドバタイズされる製品 (製品がインストールされていないなど) をスキップします。

MsiEnumProductsEx によって列挙された各製品インスタンスに関する状態またはその他の情報を取得するには、MsiGetProductInfoEx を使用します。

注意

msi.h ヘッダーは、MSIEnumProductsEx をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows Server 2012、Windows 8、Windows Server 2008 R2、または Windows 7 の Windows インストーラー 5.0。 Windows Server 2008 または Windows Vista の Windows インストーラー 4.0 または Windows インストーラー 4.5。 Windows Server 2003 または Windows XP 上では Windows インストーラー 3.0 以降。 Windows インストーラーのバージョンに必要な最小の Windows Service Pack については、Windows インストーラーの実行時の要件に関する記事を参照してください。
対象プラットフォーム Windows
ヘッダー msi.h
Library Msi.lib
[DLL] Msi.dll

こちらもご覧ください

MsiEnumProducts

Windows インストーラー 2.0 以前ではサポートされていません

ProductCode

パッチの削除