User mode transport of the library via virtual channels

In this article, we provide the library which can be used in client – server applications to cover transport layer using virtual channels. Also we attached sample add-in project (client side) and sample server application.

Contents:

General description
Library description
Interface description
How to use
Build requirements
Links

General description

Virtual channels are software extensions that can be used to add functional enhancements to a Remote Desktop Services application. Examples of functional enhancements may include support for special types of hardware, audio, or other additions to the core functionality provided by the Remote Desktop Services Remote Desktop Protocol (RDP).

To use virtual channels, you should provide the server-side and client-side modules of the virtual channels application. The server-side module can be a user-mode application or a kernel-mode driver. The client-side module must be a DLL.

Library description

The user interface definitions can be found in the RdcTransport.h header file. This is the master header and should be included in you project.

Interface description

C++

struct IVirtChannel
    {
        virtual ~IVirtChannel() { }
        virtual void Write(Buffer* pBuffer) = 0; // may be a long time, need sync for multithreading
    };

This structure is used for writing data to the client\server side.

C++

struct IReadHandler
    {
        virtual ~IReadHandler(){};
        virtual void OnRead(Buffer* pBuffer) throw() = 0;
        virtual void OnReadFail(const char* what) throw() = 0;
    };

This structure is used for reading notifications from client\server side.

C++

struct IClientVirtChannelCallback
    {
        virtual ~IClientVirtChannelCallback() { }
        virtual void OnConnect() = 0;
        virtual void OnDisconnect() = 0;
        virtual void OnTerminate() = 0;
    };

Callback interfaces for providing information about the client side connection.

C++

struct IServerVirtChannelCallback
    {
        virtual ~IServerVirtChannelCallback() { }
        virtual void OnDisconnect() = 0;
        virtual void OnReconnect() = 0;
    };

Callback interfaces for providing information about the server side connection.

Build factory:

Client side:

C++

std::auto_ptr<ivirtchannel> CreateClientChannel( __in const char* szChannelName, __in PCHANNEL_ENTRY_POINTS pEntryPoints, __in IClientVirtChannelCallback* pCallback, __in IReadHandler* pReadHandler, __in bool bShowProtocol = false);

Server side:

C++

std::auto_ptr<ivirtchannel> CreateServerChannel( __in const char* szChannelName, __in LPTSTR szAddinRGSName, __in IServerVirtChannelCallback* pCallback, __in IReadHandler* pReadHandler, __in bool bShowProtocol = false);

How to use

Client side

For the creation of the add-in DLL of the mstsc.exe file, you need to implement the following function in your DLL:

C++

BOOL VCAPITYPE VirtualChannelEntry(PCHANNEL_ENTRY_POINTS  pEntryPoints)
{
}

To work with the client side transport, you need to create the global object, which will contain your transport and provide read\write interfaces. You can do this in the following way:

C++

std::auto_ptr<rdc_transport::ivirtchannel> channel; BOOL VCAPITYPE VirtualChannelEntry(PCHANNEL_ENTRY_POINTS pEntryPoints) { try { channel = rdc_transport::CreateClientChannel("Test", pEntryPoints, &connection, &reader, false); return TRUE; } catch(...) { // TODO:: add log for example return false; } }

where connection and reader are the objects, which implement the rdc_transport::IClientVirtChannelCallback and rdc_transport::IReadHandler interfaces.

Server side

To use the server side of the virtual channel transport, you need to create the transport object in your code. This object provides read\write interfaces and contain the server side of the connection. For example, it can be performed in the main function:

C++

int main()
{
std::auto_ptr<rdc_transport::ivirtchannel> ch = rdc_transport::CreateServerChannel("Test", L"Test",&cc, &rh); }

where cc and rh are the objects, which implement the rdc_transport::IServerVirtChannelCallback and rdc_transport::IReadHandler interfaces.

To close the server side connection, destroy the ch object.

You can find the sample of implementation in the test solution.

Build requirements

Software:

Visual Studio 2008 sp1.
Boost 1.40.0 source code (see http://boost.org).
Nullsoft Scriptable Install System (NSIS) 2.45 or higher (see http://nsis.sourceforge.net/) . It is used only for the sample and is not required for the library.

Environment variables:

NSIS – should contain the path where NSIS is installed;
BOOST_ROOT – should contain the path to the Boost directory.

Preparing build system

Before building the sample solution from the source code, you should perform several simple preliminary steps. First of all, you should install all the applications specified in the Build requirements section, and set the environment variables, which are also specified in the section mentioned above.

After that, you should build Boost libraries from the source code. To do this, go to the Boost directory (BOOST_ROOT) and invoke the following two commands one after another:

1) bootstrap.bat
2) bjam.exe toolset=msvc –build-type=complete

That should be enough. For more detailed information, see Boost documentation.