Dynamic Virtual Channels

 

http://www.brianmadden.com/news/43

http://blogs.msdn.com/ts/pages/ts-teleport-sample-instructions.aspx

 

http://www.codeproject.com/KB/system/TSAddinInCS.aspx

 

An important goal of the Terminal Services (TS) team is to provide a product that can easily be extended by third parties to better meet their needs.  While TS has always supported virtual channels, they had their limitations, including the limited number of channels and the difficulty involved in writing virtual channel applications.  For the 6.1 version of the client, and Windows Vista SP1 or Windows Server 2008 on the server side, Dynamic Virtual Channels (DVCs) can be used. DVCs address the limitations of the old virtual channels.  This article outlines the basics of DVCs and shows how to write a complete DVC application and client plug-in to add basic file transfer support to Terminal Services.

DVC Basics

What are Virtual Channels?

Virtual channels are bi-directional connection streams provided through the RDP protocol. Virtual channels allow third parties to establish a data pipe between the TS client and server to extend the functionality of the Remote Desktop Protocol (RDP). Examples of extra functionality provided through virtual channels are cross-TS-connection clipboard, drive, printer and smart card redirection. There are two types of virtual channels: static and dynamic. Due to the limitations of static virtual channels referenced above, dynamic virtual channels are the preferred way to extend TS functionality.

Client and Server DVC components

On the TS client side the DVC is handled through a TS client plug-in. This plug-in is a COM object, whose registered CLSID is passed to the TS client through the registry (see the attached sample). The COM object must implement the IWTSPlugin interface. On the server side any arbitrary component running in the current session can use the WTS API to establish the DVC connection, as well as send and receive data.

Channel Initialization and Usage

Client Side

1) The TS client loads the DVC plug-ins from the registry:

HKCU/Software/Microsoft/Terminal Server Client/Default/AddIns

2) The TS client invokes the Initialize() method on IWTSPlugin; and passes an IWTSVirtualChannelManager

HRESULT CTsClientPlgn::Initialize(

IWTSVirtualChannelManager *pChannelMgr

)

3) During initialization, or at any arbitrary point, the plug-in is expected to use the IWTSVirtualChannelManager to create a connection listener and pass an IWTSListenerCallback

hr = pChannelMgr->CreateListener(TSTELE_CHANNEL_NAME,

0,

pListenerCallback,

&pListener);

4) IWTSListenerCallback is notified of connection requests on the channel; IWTSListenerCallback receives an IWTSVirtualChannel for every new connection and returns a corresponding IWTSVirtualChannelCallback

HRESULT CTsListenerCallback::OnNewChannelConnection(

IWTSVirtualChannel *pChannel,

BSTR data,

BOOL *pbAccept,

IWTSVirtualChannelCallback **ppCallback )

{

*pbAccept = TRUE;

_pChannelCallback->AddRef();

*ppCallback = _pChannelCallback;

pChannel->AddRef();

_pChannel = pChannel;

5) The plug-in uses the IWTSVirtualChannel to write to and close the channel

hr = _pChannel->Write(sizeof(HRESULT), (PBYTE) &hr, NULL);

hr = _pChannel->Close();

6) The plug-in receives incoming data and channel close notifications on the IWTSVirtualChannelCallback

HRESULT CTsChannelCallback::OnDataReceived(

ULONG cbSize,

BYTE *pBuffer

);

HRESULT CTsChannelCallback::OnClose();

Server Side

1) An application issues a WTSVirtualChannelOpenEx with the WTS_CHANNEL_OPTION_DYNAMIC flag to establish the DVC connection.

hWTSHandle = WTSVirtualChannelOpenEx(

WTS_CURRENT_SESSION,

TSTELE_CHANNEL_NAME,

WTS_CHANNEL_OPTION_DYNAMIC);

2) Using the WTS handle received from the previous call a WTSVirtualChannelQuery is used to get a read/write file handle for the channel

NOTE: DuplicateHandle() is needed to be able to access the channel after freeing hWTSHandle (i.e. calling WTSVirtualChannelClose()). The output handle from DuplicateHandle() needs to be closed using CloseHandle().

BOOL bSucc = WTSVirtualChannelQuery(

hWTSHandle,

WTSVirtualFileHandle,

&vcFileHandlePtr,

&len);

...

HANDLE hWTSFileHandle = *(HANDLE *)vcFileHandlePtr;

...

bSucc = DuplicateHandle(

GetCurrentProcess(),

hWTSFileHandle,

GetCurrentProcess(),

&_hDVC,

0,

FALSE,

DUPLICATE_SAME_ACCESS);

3) Overlapped ReadFile() and WriteFile() calls are issued on the channel file handle

bRet = ReadFile(_hDVC, ReadBuf, CHANNEL_PDU_LENGTH, &BytesRead, &ovr);

bRet = WriteFile(_hDVC, pPacket, RequiredLen, &BytesWrit, &ovr);

4) To close the connection the channel file handle is closed

CloseHandle(_hDVC);

Sample: TS-Teleport

TS-Teleport is a sample application to demonstrate the end to end use of the DVC APIs. It implements a simple protocol to transport files from the TS server session to the desktop of the client machine. It does not rely on similar TS functionality like drive redirection.

The server component is a shell extension that adds an “RDP Client Desktop” entry to the “Send To” context menu. Upon receiving the list of highlighted files which the user elected to “Send to the RDP Client Desktop”, the shell extension opens the DVC and streams the files through. Upon receiving the file names and data, the client component creates those files and directories on the desktop.

The server sends a series of state dependent requests to the client by writing on the DVC and for each request it reads the status through a DVC read. Requests are start and end pairs for files and directories and data packets for file data.

Sample Files and Instructions

Please follow the link below to access sample files and instructions, including source code and installation how-to.

http://blogs.msdn.com/ts/pages/ts-teleport-sample-instructions.aspx

Author: Ahmed Tolba (SDE TS Devices Team)

Credits: Eric Holk, Zardosht Kasheff, Josh Rosenberg and the rest of the TS Devices Team