IUpdateSearcher
COMIDispatch (デュアル)comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。公式ドキュメント
サーバー上の更新プログラムを検索します。(IUpdateSearcher)
解説(Remarks)
このインターフェイスのインスタンスは、UpdateSearcher コクラスを使用して作成できます。オブジェクトを作成するには、Microsoft.Update.Searcher プログラム識別子を使用します。
メソッド 18
vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。
以降の BeginSearch メソッドおよび Search メソッドの呼び出しによって Windows Update Agent (WUA) が自動的にアップグレードされるかどうかを示す Boolean 値を取得および設定します。(Get)
| retval | VARIANT_BOOL* | out | 更新エージェントが必要に応じて自身を自動アップグレードできるかどうかを受け取る VARIANT_BOOL へのポインタである。 |
以降の BeginSearch メソッドおよび Search メソッドの呼び出しによって Windows Update Agent (WUA) が自動的にアップグレードされるかどうかを示す Boolean 値を取得および設定します。(Put)
| value | VARIANT_BOOL | in | 更新エージェントが必要に応じて自身を自動アップグレードできるかどうかを指定する VARIANT_BOOL を渡す。 |
現在のクライアントアプリケーションを識別します。(Get)
| retval | LPWSTR* | out | 検索を実行するクライアント アプリケーションの識別子を受け取る文字列ポインタである。 |
解説(Remarks)
クライアントアプリケーションがこのプロパティを設定していない場合は、Unknown 値を返します。
現在のクライアントアプリケーションを識別します。(Put)
| value | LPWSTR | in | 検索を実行するクライアント アプリケーションの識別子を指定する文字列を渡す。 |
解説(Remarks)
クライアントアプリケーションがこのプロパティを設定していない場合は、Unknown 値を返します。
検索結果内の他の更新プログラムによって置き換えられる (superseded) 更新プログラムを検索結果に含めるかどうかを示す Boolean 値を取得および設定します。(Get)
| retval | VARIANT_BOOL* | out | 新しい更新プログラムに置き換えられた可能性がある更新プログラムも検索結果に含めるかどうかを受け取る VARIANT_BOOL へのポインタである。 |
検索結果内の他の更新プログラムによって置き換えられる (superseded) 更新プログラムを検索結果に含めるかどうかを示す Boolean 値を取得および設定します。(Put)
| value | VARIANT_BOOL | in | 新しい更新プログラムに置き換えられた可能性がある更新プログラムも検索結果に含めるかどうかを指定する VARIANT_BOOL を渡す。 |
更新プログラムを検索するサーバーを示す ServerSelection 値を取得および設定します。(Get)
| retval | ServerSelection* | out | 検索に使用する更新ソースのサーバー選択種別(ServerSelection)を受け取るポインタである。 |
解説(Remarks)
ServiceID プロパティの値によって指定される、Windows Update サイト以外のサイトが検索されるのは、ServerSelection プロパティの値が ssOthers の場合のみです。
更新プログラムを検索するサーバーを示す ServerSelection 値を取得および設定します。(Put)
| value | ServerSelection | in | 検索に使用する更新ソースのサーバー選択種別(ServerSelection)を指定する。 |
解説(Remarks)
ServiceID プロパティの値によって指定される、Windows Update サイト以外のサイトが検索されるのは、ServerSelection プロパティの値が ssOthers の場合のみです。
更新プログラムの非同期検索の実行を開始します。この検索では、現在構成されている検索オプションが使用されます。
| criteria | LPWSTR | in | 検索条件を指定する文字列。 |
| onCompleted | IUnknown* | in | 非同期検索操作が完了したときに呼び出される ISearchCompletedCallback インターフェイス。 |
| state | VARIANT | in | ISearchJob インターフェイスの AsyncState プロパティによって返される、呼び出し元固有の状態。 |
| retval | ISearchJob** | out | 保留中である可能性のある現在の操作を表す ISearchJob インターフェイス。 呼び出し元は、検索操作を完了するために、返された値を EndSearch メソッドに渡します。 |
戻り値
成功した場合は S_OK を返します。それ以外の場合は、COM または Windows のエラーコードを返します。
このメソッドは次のエラーコードを返すこともあります。
| Return code | Description |
|---|---|
| パラメーター値が無効であるか、NULL です。 | |
| このメソッドはリモートコンピューターから呼び出すことはできません。 |
解説(Remarks)
検索条件構文の完全な説明については、Search を参照してください。
ISearchCompletedCallback インターフェイスを実装する代わりに、スクリプトを使用して、オートメーションオブジェクト上の DISPID 0 を持つ任意の識別子のコールバックルーチンを実装することもできます。onCompleted パラメーターの型は IUnknown* です。
アプリで非同期 WUA API を使用する場合は、タイムアウトの仕組みを実装する必要がある場合があります。非同期 WUA 操作の実行方法の詳細については、Guidelines for Asynchronous WUA Operations を参照してください。
更新プログラムの非同期検索を完了します。
| searchJob | ISearchJob* | in | BeginSearch メソッドが返す ISearchJob インターフェイス。 |
| retval | ISearchResult** | out | 次の内容を含む ISearchResult インターフェイス。
|
戻り値
成功した場合は S_OK を返します。それ以外の場合は、COM または Windows のエラーコードを返します。
このメソッドは次のエラーコードを返すこともあります。
| Return code | Description |
|---|---|
| 更新プログラムの非同期検索が成功しました。 | |
| IUpdateSearcher の ServerSelection プロパティが ssManagedServer または ssDefault に設定されており、かつコンピューター上の管理対象サーバーが Microsoft Software Update Services (SUS) 1.0 サーバーである場合は、更新プログラムを検索できません。 | |
| パラメーター値が無効であるか、NULL です。 | |
| このメソッドはリモートコンピューターから呼び出すことはできません。 | |
| 検索ジョブに対して EndSearch が既に呼び出されている場合、EndSearch メソッドは WU_E_INVALID_OPERATION を返します。 | |
| 検索中に無効な条件が検出されました。 |
解説(Remarks)
アプリで非同期 WUA API を使用する場合は、タイムアウトの仕組みを実装する必要がある場合があります。非同期 WUA 操作の実行方法の詳細については、Guidelines for Asynchronous WUA Operations を参照してください。
文字列を、検索条件文字列内のリテラル値として使用できる文字列に変換します。
| unescaped | LPWSTR | in | エスケープする文字列。 |
| retval | LPWSTR* | out | エスケープされた結果の文字列。 |
戻り値
成功した場合は S_OK を返します。それ以外の場合は、COM または Windows のエラーコードを返します。
このメソッドは次のエラーコードを返すこともあります。
| Return code | Description |
|---|---|
| パラメーター値が無効であるか、NULL です。 |
更新プログラムイベントの履歴について、コンピューターを同期的に照会します。
| startIndex | INT | in | 取得する最初のイベントのインデックス。 |
| count | INT | in | 取得するイベントの数。 |
| retval | IUpdateHistoryEntryCollection** | out | コンピューター上で一致するイベントレコードを時系列の降順で含む IUpdateHistoryEntryCollection インターフェイスへのポインター。 |
戻り値
成功した場合は S_OK を返します。それ以外の場合は、COM または Windows のエラーコードを返します。
このメソッドは次のエラーコードを返すこともあります。
| Return code | Description |
|---|---|
| パラメーター値が無効であるか、NULL です。 | |
| インデックスが無効です。 |
解説(Remarks)
startIndex パラメーターが 0 (ゼロ) 未満の場合、または Count パラメーターが 0 (ゼロ) 以下の場合、このメソッドは WU_E_INVALIDINDEX を返します。
更新プログラムの同期検索を実行します。この検索では、現在構成されている検索オプションが使用されます。
| criteria | LPWSTR | in | 検索条件を指定する文字列。 |
| retval | ISearchResult** | out | 次の内容を含む ISearchResult インターフェイス。
|
戻り値
成功した場合は S_OK を返します。それ以外の場合は、COM または Windows のエラーコードを返します。
このメソッドは次のエラーコードを返すこともあります。
| Return code | Description |
|---|---|
| IUpdateSearcher インターフェイスの ServerSelection プロパティが ssManagedServer または ssDefault に設定されており、かつコンピューター上の管理対象サーバーが Microsoft Software Update Services (SUS) 1.0 サーバーである場合は、更新プログラムを検索できません。 | |
| パラメーター値が無効であるか、NULL です。 | |
| 無効な検索条件があります。 |
解説(Remarks)
criteria パラメーターに使用する文字列は、Search メソッドのカスタム検索言語に一致している必要があります。この文字列は、返す更新プログラムを決定するために評価される条件で構成されます。
各条件は、更新プログラムのプロパティ名と値を指定します。いくつかの制限はありますが、複数の条件を AND 演算子および OR 演算子で結合できます。= (等しい) 演算子と != (等しくない) 演算子の両方がサポートされています。Windows Update Agent (WUA) を使用する場合、!= (等しくない) 演算子は type 条件でのみ使用できます。
検索条件の構文は、SQL クエリ式の WHERE 句に基づいています。サポートされている条件のほとんどは、更新プログラムのプロパティに直接対応します。これらの更新プログラムのプロパティは、サーバーカタログ全体を含む仮想 XML ドキュメント内の要素に似ています。たとえば、検索条件文字列として "AutoSelectOnWebSites = 1" を指定すると、AutoSelectOnWebSites プロパティの値が VARIANT_TRUE であるすべての更新プログラムが検索によって返されます。
1 つの条件は "Name = Value" または "Name != Value" で構成されます。ここで "Name" はサポートされている条件名の 1 つであり、"Value" は文字列または整数です。AND 演算子および OR 演算子を使用して複数の条件を結合できます。ただし、OR は検索条件の最上位レベルでのみ使用できます。したがって、"(x=1 and y=1) or (z=1)" は有効ですが、"(x=1) and (y=1 or z=1)" は無効です。
サポートされる値の型は整数と文字列です。整数は 10 進数で指定する必要があり、負の数にはマイナス記号 (-) を先頭に付けます。文字列はエスケープし、単一引用符 (') で囲む必要があります。特に指定がない限り、すべての文字列比較では大文字と小文字が区別されません。
次の表は、評価の優先順位順に、公開されているサポート対象のすべての条件を示しています。今後、この一覧に条件が追加される可能性があります。
| 条件 | 型 | 使用可能な演算子 | 説明 |
|---|---|---|---|
| Type | string | =, != | "'Driver'" や "'Software'" など、特定の型の更新プログラムを検索します。 |
| DeploymentAction | string | = |
サーバーの管理者が指定するインストールやアンインストールなど、特定のアクション向けに配置されている更新プログラムを検索します。
"DeploymentAction='Installation'" は、対象コンピューターへのインストール向けに配置されている更新プログラムを検索します。"DeploymentAction='Uninstallation'" は他のクエリ条件に依存します。 "DeploymentAction='Uninstallation'" は、対象コンピューターでのアンインストール向けに配置されている更新プログラムを検索します。"DeploymentAction='Uninstallation'" は他のクエリ条件に依存します。 この条件が明示的に指定されていない場合、AND 演算子で結合された各条件のグループは "DeploymentAction='Installation'" を暗黙的に指定します。 |
| IsAssigned | int(bool) | = |
自動更新 (Automatic Updates) による配置を目的とした更新プログラムを検索します。
"IsAssigned=1" は、自動更新による配置を目的とした更新プログラムを検索します。これは他のクエリ条件に依存します。対象コンピューター上の各ローカルデバイスに対して、割り当てられた Windows ベースのドライバー更新プログラムは最大で 1 つ返されます。 "IsAssigned=0" は、自動更新による配置を目的としていない更新プログラムを検索します。 |
| BrowseOnly | int(bool) | = |
"BrowseOnly=1" は、オプションと見なされる更新プログラムを検索します。
"BrowseOnly=0" は、オプションと見なされない更新プログラムを検索します。 |
| AutoSelectOnWebSites | int(bool) | = |
AutoSelectOnWebSites プロパティが指定した値を持つ更新プログラムを検索します。
"AutoSelectOnWebSites=1" は、Windows Update によって自動的に選択されるようにフラグが設定されている更新プログラムを検索します。 "AutoSelectOnWebSites=0" は、自動更新用にフラグが設定されていない更新プログラムを検索します。 |
| UpdateID | string(UUID) | =, != |
UpdateIdentity.UpdateID プロパティの値が指定した値に一致する更新プログラムを検索します。!= 演算子と組み合わせて、UpdateIdentity.UpdateID が指定した値でないすべての更新プログラムを検索することもできます。
たとえば、"UpdateID='12345678-9abc-def0-1234-56789abcdef0'" は、UpdateIdentity.UpdateID が 12345678-9abc-def0-1234-56789abcdef0 に等しい更新プログラムを検索します。 たとえば、"UpdateID!='12345678-9abc-def0-1234-56789abcdef0'" は、UpdateIdentity.UpdateID が 12345678-9abc-def0-1234-56789abcdef0 に等しくない更新プログラムを検索します。 注 RevisionNumber 句は、= (等しい) 演算子を含む UpdateID 句と組み合わせることができます。ただし、RevisionNumber 句を、!= (等しくない) 演算子を含む UpdateID 句と組み合わせることはできません。
たとえば、"UpdateID='12345678-9abc-def0-1234-56789abcdef0' and RevisionNumber=100" を使用すると、UpdateIdentity.UpdateID が 12345678-9abc-def0-1234-56789abcdef0 に等しく、かつ UpdateIdentity.RevisionNumber が 100 に等しい更新プログラムを検索できます。 |
| RevisionNumber | int | = |
UpdateIdentity.RevisionNumber プロパティの値が指定した値に一致する更新プログラムを検索します。
たとえば、"RevisionNumber=2" は、UpdateIdentity.RevisionNumber が 2 に等しい更新プログラムを検索します。 この条件は UpdateID プロパティと組み合わせる必要があります。 |
| CategoryIDs | string(uuid) | contains | 指定したカテゴリに属する更新プログラムを検索します。 |
| IsInstalled | int(bool) | = |
対象コンピューターにインストールされている更新プログラムを検索します。
"IsInstalled=1" は、対象コンピューターにインストールされている更新プログラムを検索します。 "IsInstalled=0" は、対象コンピューターにインストールされていない更新プログラムを検索します。 |
| IsHidden | int(bool) | = |
対象コンピューターで非表示としてマークされている更新プログラムを検索します。
"IsHidden=1" は、対象コンピューターで非表示としてマークされている更新プログラムを検索します。この句を使用する場合、UpdateSearcher.IncludePotentiallySupersededUpdates プロパティを VARIANT_TRUE に設定すると、検索で非表示の更新プログラムが返されるようになります。非表示の更新プログラムは、同じ結果内の他の更新プログラムによって置き換えられている場合があります。 "IsHidden=0" は、非表示としてマークされていない更新プログラムを検索します。UpdateSearcher.IncludePotentiallySupersededUpdates プロパティが VARIANT_FALSE に設定されている場合は、非表示の更新プログラムによって置き換えられる更新プログラムが検索結果に含まれるように、この句を検索フィルター文字列に含めることをお勧めします。VARIANT_FALSE が既定値です。 |
| IsPresent | int(bool) | = |
1 に設定すると、コンピューター上に存在する更新プログラムを検索します。
"IsPresent=1" は、対象コンピューター上に存在する更新プログラムを検索します。更新プログラムが 1 つ以上の製品に対して有効な場合、その更新プログラムが 1 つ以上の製品に対してインストールされていれば、存在するものと見なされます。 "IsPresent=0" は、対象コンピューター上のいずれの製品に対してもインストールされていない更新プログラムを検索します。 |
| RebootRequired | int(bool) | = |
インストールまたはアンインストールを完了するためにコンピューターの再起動が必要な更新プログラムを検索します。
"RebootRequired=1" は、インストールまたはアンインストールを完了するためにコンピューターの再起動が必要な更新プログラムを検索します。 "RebootRequired=0" は、インストールまたはアンインストールを完了するためにコンピューターの再起動を必要としない更新プログラムを検索します。 |
検索の既定の検索条件は次のとおりです。
( IsInstalled = 0 and IsHidden = 0 )
すべての非表示の更新プログラムを検索するには (UpdateSearcher.IncludePotentiallySupersededUpdates プロパティを VARIANT_TRUE に設定して)、次の条件を使用します。
( IsHidden = 1 )
UpdateSearcher が更新プログラムを検索するためにオンラインになるかどうかを示す Boolean 値を取得および設定します。(Get)
| retval | VARIANT_BOOL* | out | 検索をオンライン(更新サーバーに接続して実行)で行うかどうかを受け取る VARIANT_BOOL へのポインタである。 |
UpdateSearcher が更新プログラムを検索するためにオンラインになるかどうかを示す Boolean 値を取得および設定します。(Put)
| value | VARIANT_BOOL | in | 検索をオンライン(更新サーバーに接続して実行)で行うかどうかを指定する VARIANT_BOOL を渡す。 |
コンピューター上の更新プログラムイベントの数を返します。
| retval | INT* | out | コンピューター上の更新プログラムイベントの数。 |
戻り値
成功した場合は S_OK を返します。それ以外の場合は、COM または Windows のエラーコードを返します。
このメソッドは次のエラーコードを返すこともあります。
| Return code | Description |
|---|---|
| パラメーター値が無効であるか、NULL です。 |
検索対象のサイトが Windows Update サイトではない場合に検索するサイトを取得および設定します。(Get)
| retval | LPWSTR* | out | 検索に使用する更新サービスの識別子(GUID 文字列)を受け取る文字列ポインタである。 |
解説(Remarks)
ServiceID プロパティの値によって指定される、Windows Update サイト以外のサイトが検索されるのは、ServerSelection プロパティの値が ssOthers の場合のみです。
検索対象のサイトが Windows Update サイトではない場合に検索するサイトを取得および設定します。(Put)
| value | LPWSTR | in | 検索に使用する更新サービスの識別子(GUID 文字列)を指定する文字列を渡す。 |
解説(Remarks)
ServiceID プロパティの値によって指定される、Windows Update サイト以外のサイトが検索されるのは、ServerSelection プロパティの値が ssOthers の場合のみです。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IUpdateSearcher "{8F45ABF1-F9AE-4B95-A933-F0F66E5056EA}" #usecom global IUpdateSearcher IID_IUpdateSearcher "{B699E5E8-67FF-4177-88B0-3684A3388BFB}" #comfunc global IUpdateSearcher_get_CanAutomaticallyUpgradeService 7 var #comfunc global IUpdateSearcher_put_CanAutomaticallyUpgradeService 8 int #comfunc global IUpdateSearcher_get_ClientApplicationID 9 var #comfunc global IUpdateSearcher_put_ClientApplicationID 10 wstr #comfunc global IUpdateSearcher_get_IncludePotentiallySupersededUpdates 11 var #comfunc global IUpdateSearcher_put_IncludePotentiallySupersededUpdates 12 int #comfunc global IUpdateSearcher_get_ServerSelection 13 var #comfunc global IUpdateSearcher_put_ServerSelection 14 int #comfunc global IUpdateSearcher_BeginSearch 15 wstr,sptr,int,sptr #comfunc global IUpdateSearcher_EndSearch 16 sptr,sptr #comfunc global IUpdateSearcher_EscapeString 17 wstr,var #comfunc global IUpdateSearcher_QueryHistory 18 int,int,sptr #comfunc global IUpdateSearcher_Search 19 wstr,sptr #comfunc global IUpdateSearcher_get_Online 20 var #comfunc global IUpdateSearcher_put_Online 21 int #comfunc global IUpdateSearcher_GetTotalHistoryCount 22 var #comfunc global IUpdateSearcher_get_ServiceID 23 var #comfunc global IUpdateSearcher_put_ServiceID 24 wstr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。 ; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。#define global IID_IUpdateSearcher "{8F45ABF1-F9AE-4B95-A933-F0F66E5056EA}" #usecom global IUpdateSearcher IID_IUpdateSearcher "{B699E5E8-67FF-4177-88B0-3684A3388BFB}" #comfunc global IUpdateSearcher_get_CanAutomaticallyUpgradeService 7 sptr #comfunc global IUpdateSearcher_put_CanAutomaticallyUpgradeService 8 int #comfunc global IUpdateSearcher_get_ClientApplicationID 9 sptr #comfunc global IUpdateSearcher_put_ClientApplicationID 10 wstr #comfunc global IUpdateSearcher_get_IncludePotentiallySupersededUpdates 11 sptr #comfunc global IUpdateSearcher_put_IncludePotentiallySupersededUpdates 12 int #comfunc global IUpdateSearcher_get_ServerSelection 13 sptr #comfunc global IUpdateSearcher_put_ServerSelection 14 int #comfunc global IUpdateSearcher_BeginSearch 15 wstr,sptr,int,sptr #comfunc global IUpdateSearcher_EndSearch 16 sptr,sptr #comfunc global IUpdateSearcher_EscapeString 17 wstr,sptr #comfunc global IUpdateSearcher_QueryHistory 18 int,int,sptr #comfunc global IUpdateSearcher_Search 19 wstr,sptr #comfunc global IUpdateSearcher_get_Online 20 sptr #comfunc global IUpdateSearcher_put_Online 21 int #comfunc global IUpdateSearcher_GetTotalHistoryCount 22 sptr #comfunc global IUpdateSearcher_get_ServiceID 23 sptr #comfunc global IUpdateSearcher_put_ServiceID 24 wstr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。 ; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。