ホーム › System.DesktopSharing › IRDPSRAPIViewer

IRDPSRAPIViewer

COMIDispatch (デュアル)

📘 Microsoft Learn (日本語) · English

✅ IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。

IIDc6bfcd38-8ce9-404d-8ae8-f31d00c65cb5継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

ビューアー側で使用される ActiveX インターフェイスです。

メソッド 14

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

vtbl 7 HRESULT Connect(LPWSTR bstrConnectionString, LPWSTR bstrName, LPWSTR bstrPassword)

共有側 (sharer) への実際の接続を開始します。

bstrConnectionString	LPWSTR	in	共有側への接続とビューアーの認証に使用される接続文字列です。
bstrName	LPWSTR	in	ビューアーの名前です。この名前は共有側および他のビューアーに送信されます。文字列は 255 文字までに制限されます。
bstrPassword	LPWSTR	in	認証に使用されるパスワードです。パスワードは共有側から帯域外 (out-of-band) で送信されます。

戻り値

型: HRESULT

メソッドが成功した場合、戻り値は S_OK です。それ以外の場合、戻り値はエラーコードです。

解説(Remarks)

bstrConnectionString パラメーターに含まれる接続文字列は共有側で生成され、次の手順を経てビューアーが取得します。

共有側は、IRDPSRAPISharingSession::Invitations プロパティから IRDPSRAPIInvitationManager インターフェイスのインスタンスを取得します。
共有側は、IRDPSRAPIInvitationManager::CreateInvitation メソッドを呼び出して IRDPSRAPIInvitation インターフェイスのインスタンスを取得します。
共有側は、IRDPSRAPIInvitation::ConnectionString プロパティから接続文字列を取得します。
共有側は、接続文字列をファイルに保存してビューアーと共有するなど、アプリケーション定義の方法でビューアーに接続文字列を送信します。

セキュリティを高めるために、アプリケーションは共有側で招待にパスワードを関連付けることができます。こうしたパスワードは通常、接続文字列の送信に使用される手段とは別の手段でビューアーに配布されます。これはネットワークの "スニッフィング" 型の攻撃を防ぐためです。招待にパスワードが関連付けられている場合は、この API を通じてパスワードを渡す必要があります。渡さない場合、参加者は切断されます。

このプロパティに設定される bstrName 文字列は、接続の開始後に共有側へ送信されます。このプロパティは、共有側アプリケーションが表示するために利用できるフレンドリ名です。1 つの招待で複数の参加者を認証する場合に、Windows デスクトップ共有セッションに誰が参加しているかを共有側や他のビューアーが識別できるため、このプロパティは有用です。

vtbl 8 HRESULT Disconnect()

共有側からのビューアーの切断を開始します。

戻り値

メソッドが成功した場合、戻り値は S_OK です。それ以外の場合、戻り値はエラーコードです。

vtbl 9 HRESULT get_Attendees(IRDPSRAPIAttendeeManager** ppVal)

IRDPSRAPIAttendeeManager インターフェイスを実装するオブジェクトを返します。(IRDPSRAPIViewer.get_Attendees)

ppVal

IRDPSRAPIAttendeeManager**

out

セッションの参加者を管理する IRDPSRAPIAttendeeManager インターフェイスを受け取るポインタである。

vtbl 10 HRESULT get_Invitations(IRDPSRAPIInvitationManager** ppVal)

IRDPSRAPIInvitationManager インターフェイスを実装するオブジェクトを返します。(IRDPSRAPIViewer.get_Invitations)

ppVal

IRDPSRAPIInvitationManager**

out

セッションの招待を管理する IRDPSRAPIInvitationManager インターフェイスを受け取るポインタである。

vtbl 11 HRESULT get_ApplicationFilter(IRDPSRAPIApplicationFilter** ppVal)

IRDPSRAPIApplicationFilter インターフェイスを実装するオブジェクトを返します。(IRDPSRAPIViewer.get_ApplicationFilter)

ppVal

IRDPSRAPIApplicationFilter**

out

共有対象を制御するアプリケーションフィルタ IRDPSRAPIApplicationFilter インターフェイスを受け取るポインタである。

vtbl 12 HRESULT get_VirtualChannelManager(IRDPSRAPIVirtualChannelManager** ppVal)

IRDPSRAPIVirtualChannelManager インターフェイスを実装するオブジェクトを返します。

ppVal

IRDPSRAPIVirtualChannelManager**

out

仮想チャネルを管理する IRDPSRAPIVirtualChannelManager インターフェイスを受け取るポインタである。

vtbl 13 HRESULT put_SmartSizing(VARIANT_BOOL vbSmartSizing)

ビューアー ActiveX コントロールのスマートサイジングプロパティを取得または設定します。(Put)

vbSmartSizing

VARIANT_BOOL

スマートサイジング (表示領域に合わせた自動縮尺) を有効にするかどうかを指定する VARIANT_BOOL である。

vtbl 14 HRESULT get_SmartSizing(VARIANT_BOOL* pvbSmartSizing)

ビューアー ActiveX コントロールのスマートサイジングプロパティを取得または設定します。(Get)

pvbSmartSizing

VARIANT_BOOL*

out

スマートサイジングが有効かどうかを示す VARIANT_BOOL を受け取るポインタである。

vtbl 15 HRESULT RequestControl(CTRL_LEVEL CtrlLevel)

ビューアーの制御レベルを変更するよう共有側に要求します。

CtrlLevel

CTRL_LEVEL

CTRL_LEVEL 列挙型の値のいずれかです。

戻り値

型: HRESULT

メソッドが成功した場合、戻り値は S_OK です。それ以外の場合、戻り値はエラーコードです。

vtbl 16 HRESULT put_DisconnectedText(LPWSTR bstrDisconnectedText)

接続が終了する前にコントロールの中央に表示されるテキストを取得または設定します。(Put)

bstrDisconnectedText

LPWSTR

切断時に表示するテキストを指定する文字列である。

解説(Remarks)

DisconnectedText の設定は省略可能です。指定しない場合、接続が確立されるまでコントロールは空白で表示されます。

DisconnectedText プロパティは、コントロールが接続状態でない場合にのみ設定できます。コントロールの接続後に呼び出された場合、このメソッドは E_FAIL を返します。

vtbl 17 HRESULT get_DisconnectedText(LPWSTR* pbstrDisconnectedText)

接続が終了する前にコントロールの中央に表示されるテキストを取得または設定します。(Get)

pbstrDisconnectedText

LPWSTR*

out

切断時に表示されるテキストを受け取る文字列バッファへのポインタである。呼び出し側が解放する。

解説(Remarks)

DisconnectedText の設定は省略可能です。指定しない場合、接続が確立されるまでコントロールは空白で表示されます。

vtbl 18 HRESULT RequestColorDepthChange(INT Bpp)

共有側の Winlogon ユーザーセッションに対して色深度の変更を要求します。

Bpp

INT

セッションの色深度をビット/ピクセル単位で指定します。指定可能な値は 16 と 24 です。8 を指定した場合、色深度は 16 ビット/ピクセルに設定されます。

Windows Server 2008 および Windows Vista: 指定可能な値は 8、16、24 です。

戻り値

型: HRESULT

メソッドが成功した場合、戻り値は S_OK です。それ以外の場合、戻り値はエラーコードです。

vtbl 19 HRESULT get_Properties(IRDPSRAPISessionProperties** ppVal)

IRDPSRAPISessionProperties インターフェイスを実装するオブジェクトを返します。

ppVal

IRDPSRAPISessionProperties**

out

セッションのプロパティを管理する IRDPSRAPISessionProperties インターフェイスを受け取るポインタである。

vtbl 20 HRESULT StartReverseConnectListener(LPWSTR bstrConnectionString, LPWSTR bstrUserName, LPWSTR bstrPassword, LPWSTR* pbstrReverseConnectString)

共有側からビューアーへの逆方向接続 (リバースコネクト) を受け入れるためのリスナーを開始します。または、共有側がビューアーへ逆方向接続するために使用する接続文字列を取得します。

bstrConnectionString	LPWSTR	in	共有側がリスナーを開始するために使用する接続文字列です。
bstrUserName	LPWSTR	in	認証に使用するユーザー名です。
bstrPassword	LPWSTR	in	認証に使用するパスワードです。
pbstrReverseConnectString	LPWSTR*	out	共有側が IRDPSRAPISharingSession::ConnectToClient メソッドを使用してビューアーへ逆方向接続するために利用できる接続文字列を受け取る BSTR へのポインターです。

戻り値

型: HRESULT

メソッドが成功した場合、戻り値は S_OK です。それ以外の場合、戻り値はエラーコードです。

解説(Remarks)

このメソッドは、2 つの異なる操作を行うために使用します。

1 つ目は、共有側がビューアーへ逆方向接続するために使用する接続文字列を、ビューアーが取得できるようにする操作です。そのためには、bstrConnectionString、bstrUserName、bstrPassword の各パラメーターをすべて NULL にする必要があります。ビューアーはその後、接続文字列をファイルに保存して共有側と共有するなど、アプリケーション定義の方法でこの接続文字列を共有側に送信します。
2 つ目は、共有側からの逆方向接続の試行を待ち受けるリスナーを開始する操作です。この操作では、pbstrReverseConnectString パラメーターを NULL にする必要があります。

この手順における通常のイベントの流れは次のとおりです。

ビューアーは、bstrConnectionString、bstrUserName、bstrPassword の各パラメーターに NULL を渡して StartReverseConnectListener メソッドを呼び出し、自身の接続文字列を取得します。
ビューアーは、pbstrReverseConnectString パラメーターに NULL を、bstrConnectionString、bstrUserName、bstrPassword の各パラメーターに有効な値を渡して StartReverseConnectListener メソッドを呼び出し、逆方向接続リスナーを開始します。
ビューアーは、手順 1 で取得した接続文字列を共有側に送信します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IRDPSRAPIViewer "{C6BFCD38-8CE9-404D-8AE8-F31D00C65CB5}"
#usecom global IRDPSRAPIViewer IID_IRDPSRAPIViewer "{}"
#comfunc global IRDPSRAPIViewer_Connect                      7 wstr,wstr,wstr
#comfunc global IRDPSRAPIViewer_Disconnect                   8
#comfunc global IRDPSRAPIViewer_get_Attendees                9 sptr
#comfunc global IRDPSRAPIViewer_get_Invitations              10 sptr
#comfunc global IRDPSRAPIViewer_get_ApplicationFilter        11 sptr
#comfunc global IRDPSRAPIViewer_get_VirtualChannelManager    12 sptr
#comfunc global IRDPSRAPIViewer_put_SmartSizing              13 int
#comfunc global IRDPSRAPIViewer_get_SmartSizing              14 var
#comfunc global IRDPSRAPIViewer_RequestControl               15 int
#comfunc global IRDPSRAPIViewer_put_DisconnectedText         16 wstr
#comfunc global IRDPSRAPIViewer_get_DisconnectedText         17 var
#comfunc global IRDPSRAPIViewer_RequestColorDepthChange      18 int
#comfunc global IRDPSRAPIViewer_get_Properties               19 sptr
#comfunc global IRDPSRAPIViewer_StartReverseConnectListener  20 wstr,wstr,wstr,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。#define global IID_IRDPSRAPIViewer "{C6BFCD38-8CE9-404D-8AE8-F31D00C65CB5}"
#usecom global IRDPSRAPIViewer IID_IRDPSRAPIViewer "{}"
#comfunc global IRDPSRAPIViewer_Connect                      7 wstr,wstr,wstr
#comfunc global IRDPSRAPIViewer_Disconnect                   8
#comfunc global IRDPSRAPIViewer_get_Attendees                9 sptr
#comfunc global IRDPSRAPIViewer_get_Invitations              10 sptr
#comfunc global IRDPSRAPIViewer_get_ApplicationFilter        11 sptr
#comfunc global IRDPSRAPIViewer_get_VirtualChannelManager    12 sptr
#comfunc global IRDPSRAPIViewer_put_SmartSizing              13 int
#comfunc global IRDPSRAPIViewer_get_SmartSizing              14 sptr
#comfunc global IRDPSRAPIViewer_RequestControl               15 int
#comfunc global IRDPSRAPIViewer_put_DisconnectedText         16 wstr
#comfunc global IRDPSRAPIViewer_get_DisconnectedText         17 sptr
#comfunc global IRDPSRAPIViewer_RequestColorDepthChange      18 int
#comfunc global IRDPSRAPIViewer_get_Properties               19 sptr
#comfunc global IRDPSRAPIViewer_StartReverseConnectListener  20 wstr,wstr,wstr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。