ホーム › System.RemoteDesktop › IWTSSBPlugin

IWTSSBPlugin

COM

IIDdc44be78-b18d-4399-b210-641bf67a002c継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ターミナルサービスセッションブローカー (TS Session Broker) の機能を拡張するために使用します。TS Session Broker のリダイレクトロジックをオーバーライドするプラグインを提供する場合に、このインターフェイスを実装します。

解説(Remarks)

TS Session Broker は WTSSBX_GetUserExternalSession メソッドを呼び出し、プラグインが受信接続を TS Session Broker のファームに属さないコンピューターに振り向けられるようにします。

あるいは、TS Session Broker は WTSSBX_GetMostSuitableServer メソッドを呼び出し、プラグインが受信接続を TS Session Broker のファームに属するコンピューターに振り向けられるようにします。

これらのメソッドは、TS Session Broker がサーバーに割り当てた一意の MachineId を使用して、ファーム内の個々のサーバーを参照します。サーバーが TS Session Broker のファームに参加すると、TS Session Broker は WTSSBX_MachineChangeNotification メソッドを呼び出してプラグインに変更を通知し、新しいサーバーの MachineId をプラグインに渡します。

メソッド 6

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT Initialize(DWORD* PluginCapabilities)

プラグインを初期化し、プラグインのリダイレクト機能を示す値を返します。

PluginCapabilities

DWORD*

out

プラグインのリダイレクト機能を示す値へのポインター。

0

プラグインは TS Session Broker のファーム内でのみリダイレクトします。この値が返された場合、TS Session Broker はプラグインの WTSSBX_GetUserExternalSession メソッドを呼び出しません。

1

プラグインは TS Session Broker のファーム内でリダイレクトし、さらに WTSSBX_GetUserExternalSession を実装してファーム外へのリダイレクトを行います。

戻り値

成功した場合は S_OK を返します。

解説(Remarks)

TS Session Broker は COM クラスをインスタンス化した直後に Initialize を呼び出します。プラグインは、Initialize メソッドを使用して自身のリダイレクト機能に関する情報を返す必要があります。

Initialize の実装は、成功した場合は直ちに S_OK を返す必要があります。

vtbl 4 HRESULT WTSSBX_MachineChangeNotification(WTSSBX_NOTIFICATION_TYPE NotificationType, INT MachineId, WTSSBX_MACHINE_INFO* pMachineInfo)

サーバー環境で変更が発生したことをプラグインに通知します。

NotificationType	WTSSBX_NOTIFICATION_TYPE	in	発生したイベントの種類を示す WTSSBX_NOTIFICATION_TYPE 列挙型の値。
MachineId	INT	in	変更が発生したサーバーの ID。
pMachineInfo	WTSSBX_MACHINE_INFO*	in	変更されたサーバーに関する情報を格納する WTSSBX_MACHINE_INFO 構造体へのポインター。この構造体では、変更されたメンバーのみが報告されます。その他のメンバーは 0 に設定されます。

戻り値

成功した場合は S_OK を返します。

解説(Remarks)

ターミナルサービスセッションブローカー (TS Session Broker) は、サーバー環境で重要な変更が発生するたびにこのメソッドを呼び出します。たとえば、呼び出しのきっかけとなる変更には次のようなものがあります。

サーバーが TS Session Broker のファームに参加する、またはファームから離脱する。
サーバーがドレイン状態を変更する。
サーバーの IP アドレスが変更される。
サーバーの最大セッション数の上限が変更される。

このメソッドの実装は、成功した場合は直ちに S_OK を返す必要があります。

vtbl 5 HRESULT WTSSBX_SessionChangeNotification(WTSSBX_NOTIFICATION_TYPE NotificationType, INT MachineId, DWORD NumOfSessions, WTSSBX_SESSION_INFO* SessionInfo)

ログオン、ログオフ、切断、再接続などの変更がセッションで発生したことをプラグインに通知します。

NotificationType	WTSSBX_NOTIFICATION_TYPE	in	発生した変更の種類を指定する WTSSBX_NOTIFICATION_TYPE 型。
MachineId	INT	in	セッションの変更が発生したサーバーの ID。
NumOfSessions	DWORD	in	SessionInfo 配列の要素数。
SessionInfo	WTSSBX_SESSION_INFO*	in	セッションに関する情報を格納する WTSSBX_SESSION_INFO 構造体の配列。この構造体では、変更されたメンバーのみが報告されます。その他は 0 に設定されます。

戻り値

成功した場合は S_OK を返します。

解説(Remarks)

WTSSBX_SessionChangeNotification メソッドは、1 回の呼び出しにつき最大 25 個のセッションを報告できます。ターミナルサービスセッションブローカー (TS Session Broker) が 25 個を超えるセッションを報告する必要がある場合は、すべてのセッションを報告し終えるまでこのメソッドを複数回呼び出します。

このメソッドの実装は、成功した場合は直ちに S_OK を返す必要があります。

vtbl 6 HRESULT WTSSBX_GetMostSuitableServer(LPWSTR UserName, LPWSTR DomainName, LPWSTR ApplicationType, LPWSTR FarmName, INT* pMachineId)

ターミナルサービスセッションブローカー (TS Session Broker) が受信接続を振り向けるべきサーバーの ID を返します。

UserName	LPWSTR	in	受信接続のユーザー名を格納する Unicode 文字列へのポインター。
DomainName	LPWSTR	in	受信接続に関連付けられているドメイン名を格納する Unicode 文字列へのポインター。
ApplicationType	LPWSTR	in	リモートデスクトップサービスがセッションを作成した後に実行するプログラムの名前を格納する Unicode 文字列へのポインター。
FarmName	LPWSTR	in	ユーザーの接続先となる TS Session Broker のファームの名前を格納する Unicode 文字列へのポインター。
pMachineId	INT*	inout	TS Session Broker が受信接続をリダイレクトするサーバーの ID へのポインター。この値は、初期状態では TS Session Broker の負荷分散ロジックによって提供されたサーバーの ID に設定されています。

戻り値

成功した場合は S_OK を返します。

解説(Remarks)

TS Session Broker の既定の負荷分散ロジックをオーバーライドするには、WTSSBX_GetMostSuitableServer を使用します。TS Session Broker は、自身の負荷分散ロジックを実行した後にこのメソッドを呼び出します。pMachineId パラメーターは、初期状態では TS Session Broker の負荷分散ロジックによって提供されたサーバーの ID に設定されています。このメソッドを実装する際、リダイレクトロジックはこの pMachineId を返すことも、適切であれば別の ID を返すこともできます。

サーバーが TS Session Broker のファームに参加するたびに、TS Session Broker は WTSSBX_MachineChangeNotification メソッドを呼び出してプラグインに通知し、新しいサーバーを識別するための MachineId を提供します。TS Session Broker が WTSSBX_GetMostSuitableServer を呼び出したとき、プラグインは TS Session Broker がプラグインに提供した ID のいずれかを返す必要があります。プラグインは、ファームに存在しないサーバーの ID を返してはなりません。

WTSSBX_GetMostSuitableServer の実装は、成功した場合は直ちに S_OK を返す必要があります。

vtbl 7 HRESULT Terminated()

ターミナルサービスセッションブローカー (TS Session Broker) によってプラグインが破棄されようとしていることを、そのプラグインに通知します。

戻り値

成功した場合は S_OK を返します。

解説(Remarks)

TS Session Broker は、このプラグインのインスタンスを破棄する前にこのメソッドを呼び出します。このメソッドを使用して、TS Session Broker がプラグインを破棄する前にプラグインのクリーンアップを実行できます。プラグインが破棄されると、TS Session Broker は本来のリダイレクトサービスに戻ります。

このメソッドの実装は、成功した場合は直ちに S_OK を返す必要があります。

vtbl 8 HRESULT WTSSBX_GetUserExternalSession(LPWSTR UserName, LPWSTR DomainName, LPWSTR ApplicationType, WTSSBX_IP_ADDRESS* RedirectorInternalIP, DWORD* pSessionId, WTSSBX_MACHINE_CONNECT_INFO* pMachineConnectInfo)

リソースに関する情報を格納する WTSSBX_MACHINE_CONNECT_INFO 構造体を提供することにより、受信接続を仮想マシン、ブレードサーバー、あるいはユーザー自身の社内デスクトップなどのコンピューティングリソースにリダイレクトします。

UserName	LPWSTR	in	受信接続のユーザー名を格納する Unicode 文字列へのポインター。
DomainName	LPWSTR	in	受信接続のドメイン名を格納する Unicode 文字列へのポインター。
ApplicationType	LPWSTR	in	ユーザーセッションの作成後にリモートデスクトップサービスが実行するプログラムを格納する Unicode 文字列へのポインター。
RedirectorInternalIP	WTSSBX_IP_ADDRESS*	in	最初に接続を受け入れた RD Session Host サーバーの内部 IP アドレスへのポインター。
pSessionId	DWORD*	out	プラグインが受信接続をリダイレクトする先のセッションのセッション ID へのポインター。
pMachineConnectInfo	WTSSBX_MACHINE_CONNECT_INFO*	out	プラグインが受信接続を振り向ける先のコンピューターに関する情報を格納する WTSSBX_MACHINE_CONNECT_INFO 構造体へのポインター。

戻り値

成功した場合は S_OK を返します。

解説(Remarks)

ターミナルサービスセッションブローカー (TS Session Broker) はこのメソッドを呼び出し、プラグインが受信接続を TS Session Broker のファームに参加していないコンピューターにリダイレクトできるようにします。

WTSSBX_GetUserExternalSession の実装は、TS Session Broker のファームに参加していないコンピューターへのリダイレクトをサポートしない場合、E_NOTIMPL を返す必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IWTSSBPlugin "{DC44BE78-B18D-4399-B210-641BF67A002C}"
#usecom global IWTSSBPlugin IID_IWTSSBPlugin "{}"
#comfunc global IWTSSBPlugin_Initialize                        3 var
#comfunc global IWTSSBPlugin_WTSSBX_MachineChangeNotification  4 int,int,var
#comfunc global IWTSSBPlugin_WTSSBX_SessionChangeNotification  5 int,int,int,var
#comfunc global IWTSSBPlugin_WTSSBX_GetMostSuitableServer      6 wstr,wstr,wstr,wstr,var
#comfunc global IWTSSBPlugin_Terminated                        7
#comfunc global IWTSSBPlugin_WTSSBX_GetUserExternalSession     8 wstr,wstr,wstr,var,var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IWTSSBPlugin "{DC44BE78-B18D-4399-B210-641BF67A002C}"
#usecom global IWTSSBPlugin IID_IWTSSBPlugin "{}"
#comfunc global IWTSSBPlugin_Initialize                        3 sptr
#comfunc global IWTSSBPlugin_WTSSBX_MachineChangeNotification  4 int,int,sptr
#comfunc global IWTSSBPlugin_WTSSBX_SessionChangeNotification  5 int,int,int,sptr
#comfunc global IWTSSBPlugin_WTSSBX_GetMostSuitableServer      6 wstr,wstr,wstr,wstr,sptr
#comfunc global IWTSSBPlugin_Terminated                        7
#comfunc global IWTSSBPlugin_WTSSBX_GetUserExternalSession     8 wstr,wstr,wstr,sptr,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。