Win32 API 日本語リファレンス
ホーム › System.RemoteManagement › IWSManSession

IWSManSession

COMIDispatch (デュアル)
📘 Microsoft Learn (日本語) · English
✅ IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。
IIDfc84fc58-1286-40c4-9da0-c8ef6ec241e0継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

操作とセッション設定を定義します。

メソッド 12

vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。

vtbl 7 HRESULT Get(VARIANT resourceUri, INT flags, LPWSTR* resource)

URI で指定されたリソースを取得し、そのリソースの現在のインスタンスの XML 表現を返します。

resourceUriVARIANTin

取得するリソースの識別子です。

このパラメーターには、次のいずれかを指定できます。

  • セレクター の有無にかかわらず指定する URI。WMI リソースを取得するために Get メソッドを呼び出す場合は、オブジェクトのキープロパティを使用します。
  • ResourceLocator オブジェクト。セレクター、フラグメント、または オプション を含めることができます。
  • WS-Management プロトコル標準で説明されている WS-Addressing エンドポイント参照。WS-Management プロトコルの公開仕様の詳細については、Management Specifications Index Page を参照してください。
flagsINTin将来使用するために予約されています。0 に設定する必要があります。
resourceLPWSTR*out成功した場合、リソースの XML 表現となる値です。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 8 HRESULT Put(VARIANT resourceUri, LPWSTR resource, INT flags, LPWSTR* resultResource)

リソースを更新します。

resourceUriVARIANTin

更新するリソースの識別子です。

このパラメーターには、次のいずれかを指定できます。

  • セレクター の有無にかかわらず指定する URI。WMI リソースを取得するために Put メソッドを呼び出す場合は、オブジェクトのキープロパティを使用します。
  • ResourceLocator オブジェクト。セレクター、フラグメント、または オプション を含めることができます。
  • WS-Management プロトコル標準で説明されている WS-Addressing エンドポイント参照。WS-Management プロトコルの公開仕様の詳細については、Management Specifications Index Page を参照してください。
resourceLPWSTRin更新後のリソースの内容です。
flagsINTin将来使用するために予約されています。0 に設定する必要があります。
resultResourceLPWSTR*out更新後のリソースの内容を含む XML ストリームです。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 9 HRESULT Create(VARIANT resourceUri, LPWSTR resource, INT flags, LPWSTR* newUri)

リソースの新しいインスタンスを作成し、新しいオブジェクトのエンドポイント参照 (EPR) を返します。

resourceUriVARIANTin

作成するリソースの識別子です。

このパラメーターには、次のいずれかを指定できます。

resourceLPWSTRinリソースの内容を含む XML 文字列です。
flagsINTin予約されています。0 に設定する必要があります。
newUriLPWSTR*out新しいリソースの EPR です。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

IWSManSession::Create は、リソースの新しいインスタンスを作成する場合にのみ使用します。既存のリソースのインスタンスを更新するには、IWSManSession::Put メソッドを使用してください。新しいリソースの URI を取得した後、IWSManSession::Get を呼び出して新しいオブジェクトを取得できます。新しいオブジェクトには、リソースプロバイダーが新しいオブジェクトの作成時に割り当てたプロパティが含まれます。たとえば、新しい WS-Management プロトコル リスナー を作成し、Session.Get を使用してリスナーオブジェクトを取得すると、Port、Enabled、ListeningOn の各プロパティも取得できます。

vtbl 10 HRESULT Delete(VARIANT resourceUri, INT flags)

リソース URI で指定されたリソースを削除します。

resourceUriVARIANTin削除するリソースの URI です。IWSManResourceLocator オブジェクトを使用してリソースを指定することもできます。
flagsINTin将来使用するために予約されています。0 に設定する必要があります。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 11 HRESULT Invoke(LPWSTR actionUri, VARIANT resourceUri, LPWSTR parameters, INT flags, LPWSTR* result)

メソッドを呼び出し、そのメソッド呼び出しの結果を返します。

actionUriLPWSTRin呼び出すメソッドの URI です。
resourceUriVARIANTin

メソッドを呼び出すリソースの識別子です。

このパラメーターには、次のいずれかを指定できます。

parametersLPWSTRinメソッドへの入力の XML 表現です。この文字列を指定しないと、このメソッドは失敗します。
flagsINTin将来使用するために予約されています。0 に設定する必要があります。
resultLPWSTR*outメソッドの出力の XML 表現です。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 12 HRESULT Enumerate(VARIANT resourceUri, LPWSTR filter, LPWSTR dialect, INT flags, IDispatch** resultSet)

テーブル、データコレクション、またはログリソースを列挙します。

resourceUriVARIANTin

取得するリソースの識別子です。

次の一覧は、このパラメーターに指定できる識別子です。

filterLPWSTRin

列挙によってリソース内のどの項目を返すかを定義するフィルターです。リソースが列挙されると、フィルター条件に一致する項目のみが返されます。列挙に filter パラメーターと dialect パラメーターを含めると、その列挙はクエリに変換されます。

resourceURI パラメーターに IWSManResourceLocator オブジェクトを指定している場合は、このパラメーターを使用しないでください。代わりに、IWSManResourceLocator のセレクターおよびフラグメント機能を使用してください。

dialectLPWSTRin

フィルターで使用される言語です。サポートされている言語は、WMI で使用される SQL のサブセットである WQL のみです。

resourceURI パラメーターに IWSManResourceLocator オブジェクトを指定している場合は、このパラメーターを使用しないでください。代わりに、IWSManResourceLocator のセレクターおよびフラグメント機能を使用してください。

flagsINTinこのパラメーターには、__WSManEnumFlags 列挙内のフラグを指定する必要があります。詳細については、Enumeration Constants を参照してください。
resultSetIDispatch**out列挙の結果を含む IWSManEnumerator オブジェクトです。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

列挙操作を開始するには、IWSManSession::Enumerate を呼び出します。その後、返された IWSManEnumerator オブジェクトを使用して、AtEndOfStream プロパティによって項目の終端が示されるまで IWSManEnumerator::ReadItem を呼び出します。

フラグに Enumeration Constants の WSManFlagHierarchyDeepBasePropsOnly または WSManFlagHierarchyShallow が含まれている場合、Windows Remote Management サービスはエラーコード ERROR_WSMAN_POLYMORPHISM_MODE_UNSUPPORTED を返すことに注意してください。

列挙中のネットワーク呼び出しを制限する方法の詳細については、BatchItems プロパティを参照してください。

フィルターを指定する場合は、リソースのスキーマに照らして有効なドキュメントである必要があります。dialect パラメーターは省略可能です。ただし、フィルター文字列が < で始まるものの XML フラグメントではない場合は、dialect パラメーターを含めるか、flags パラメーターに WSManFlagNonXmlText フラグを設定してください。詳細については、Enumeration Constants を参照してください。

対応するスクリプティングメソッドは Session.Enumerate です。

vtbl 13 HRESULT Identify(INT flags, LPWSTR* result)

リモートコンピューターに照会して、WS-Management プロトコルをサポートしているかどうかを確認します。

flagsINTin受け付けられるフラグは WSManFlagUseNoAuthentication のみです。
resultLPWSTR*out成功した場合、WS-Management プロトコルのバージョン、オペレーティングシステムのベンダー、および要求が認証付きで送信された場合はオペレーティングシステムのバージョンを指定する XML 文字列となる値です。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 14 HRESULT get_Error(LPWSTR* value)

直前の IWSManSession オブジェクトのメソッド呼び出しに関する追加のエラー情報を XML ストリームで取得します。

valueLPWSTR*out直近の操作で発生したエラーの詳細を表す XML 文字列を受け取る。受け取った文字列は呼び出し側で解放する。
vtbl 15 HRESULT get_BatchItems(INT* value)

各列挙バッチ内の項目数を設定および取得します。(Get)

valueINT*out列挙時に一度に取得するアイテム数(バッチサイズ)を受け取る。

解説(Remarks)

これは、クライアントとサーバー間でネットワーク呼び出しが行われる頻度を制御する最適化機能です。現在は列挙にのみ使用されます。リソースの列挙の詳細については、IWSManEnumerator を参照してください。

vtbl 16 HRESULT put_BatchItems(INT value)

各列挙バッチ内の項目数を設定および取得します。(Put)

valueINTin列挙時に一度に取得するアイテム数(バッチサイズ)を指定する。

解説(Remarks)

これは、クライアントとサーバー間でネットワーク呼び出しが行われる頻度を制御する最適化機能です。現在は列挙にのみ使用されます。リソースの列挙の詳細については、IWSManEnumerator を参照してください。

vtbl 17 HRESULT get_Timeout(INT* value)

クライアントアプリケーションが Windows Remote Management の操作完了を待機する最大時間 (ミリ秒単位) を設定および取得します。(Get)

valueINT*out操作のタイムアウト時間をミリ秒単位で受け取る。
vtbl 18 HRESULT put_Timeout(INT value)

クライアントアプリケーションが Windows Remote Management の操作完了を待機する最大時間 (ミリ秒単位) を設定および取得します。(Put)

valueINTin操作のタイムアウト時間をミリ秒単位で指定する。
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IWSManSession "{FC84FC58-1286-40C4-9DA0-C8EF6EC241E0}"
#usecom global IWSManSession IID_IWSManSession "{}"
#comfunc global IWSManSession_Get             7 int,int,var
#comfunc global IWSManSession_Put             8 int,wstr,int,var
#comfunc global IWSManSession_Create          9 int,wstr,int,var
#comfunc global IWSManSession_Delete          10 int,int
#comfunc global IWSManSession_Invoke          11 wstr,int,wstr,int,var
#comfunc global IWSManSession_Enumerate       12 int,wstr,wstr,int,sptr
#comfunc global IWSManSession_Identify        13 int,var
#comfunc global IWSManSession_get_Error       14 var
#comfunc global IWSManSession_get_BatchItems  15 var
#comfunc global IWSManSession_put_BatchItems  16 int
#comfunc global IWSManSession_get_Timeout     17 var
#comfunc global IWSManSession_put_Timeout     18 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。