Dynamic Virtual Channels

Dynamic Virtual Channels

  • Comments 8

 

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.

dvc

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

Leave a Comment
  • Please add 3 and 4 and type the answer here:
  • Post
  • The Terminal Services Team Blog has a great blog entry published recently where they describe the support that has been added for dynamic virtual channel drivers within RDP. Most of us are aware ...

  • Thank you for the great info!

    <a href="http://www.infinitelyvirtual.com/categories/applications/virtual-terminal-server.html">InfinitelyVirtual.com</a>

  • Hi, Nadim here again. Today we’re wrapping up our Top 10 list of RDP Misconceptions. So without further

  • How would one go about using a DVC to do TCP port forwarding? In cases where the LAN firewall lets RDP through but not (say) LDAP, it would be useful.

  • The MSDN says that "The server component can be a user-mode application or a kernel-mode driver". So far I have not found any information on writing the driver. Could someone point me in the right direction. A example would do nicely.

  • What's the matter when you need to need to establish a virtual channel between a windows seven client and a 2003 Server?. What kind of implementation is suggested if 2003 doest support DVC's and Seven doesn't support SVC?

  • We are looking for the ability to turn on and off file transfer on the server side to connected in remote client, and when file transfer is turned on to have the ability to monitor and possibly turn off the file transfer based on file content. Are there any existing VC services to build this on?

    Thanks

  • Hello,

    I am just exploring Dynamic Virtual Channels. I have couple of concerns on this.

    1. I have a web service running on physical system and I want to access that web service over RDP or from Cloud system (means from the system that is running in different network/domain than the physical system). Is this possible using Dynamic Virtual Channels

    2. Also, by using Dynamic Virtual Channels can I send command line arguments from RDP server to client side and launch specific application that is available on client system.

Page 1 of 1 (8 items)