Writing Plugins for RDesktop

Contents

• About this Article: When It's Worth Reading
• Rdesktop. RDP Protocol
• Writing Plugins to rdesktop: Using OOP Patch
• From Principles to Code
• Client Part: Plugin
• Client Part: rdesktop
• Server Part
• The End
• History 

About this Article: When It’s Worth Reading

This article was mostly written for Linux developers. The article gives a method of writing out-of-process plugins to open source software – i.e., plugins that will work as a part of the software but will run in another process, so their code may stay closed.

Generally there’s no need to use the method expounded in this text. Rdesktop is free software and you can always just modify its sources in any way you need. Though, this would mean that you should make your code open as well, because this is what GPL license requires. If you don’t want this though, keep reading and you’ll learn how to avoid the GPL requirement and to write a plugin whose code will be closed but work as a part of Rdesktop code.

You may also want to read this just to know something interesting about:

• RDP protocol
• Rdesktop – an open-source RDP client
• A simple way of inter-process communication on *nix systems.

Let's get started.

Rdesktop. RDP Protocol

This is for those who don’t know what it is all about. Remote Desktop Protocol (RDP) is a proprietary protocol developed by Microsoft, which concerns providing a user with a graphical interface to another computer. This is very handy – you can work on another computer sitting at your desktop with almost no differences in appearance and performance (of course, if you have a good network connection – hi-speed, with small latency, and so on and so forth). There’re RDP clients for almost all operating systems – Windows, Linux, Mac OS, and all of them use RDP protocol to connect to an RDP server – a remote host that you want to work with. In 2008 Microsoft opened RDP specifications, now they are available at their site: http://msdn.microsoft.com/en-us/library/cc216513(PROT.10).aspx.

Rdesktop is an open source client for Windows Terminal Services. It currently runs on most UNIX based platforms with the X Window System. It supports most of the basic RDP protocol features, and many protocol extensions, including audio redirection, clipboard, local file system and local devices redirection. Rdesktop is released under the GNU Public License (GPL).

Just like many other *nix programs, Rdesktop is a command-line application. It has a lot of various input parameters that configure a remote session – user credentials, server address, desktop dimensions, color depth; also description of local devices that are to be redirected to the remote computer – comports, printers, sound, disks.

On parsing its command line and starting a session to a remote host, rdesktop enters an endless loop in which it reads incoming data, i.e., the data sent by server, and sends some data to the server in response. The connection with the server is made via so-called virtual channels. Microsoft has a floor:

"Virtual channels are software extensions that can be used to add functional enhancements to a Remote Desktop Services application. Examples of functional enhancements might 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). The RDP protocol provides multiplexed management of multiple virtual channels.
A virtual channel application has two parts, a client-side component and a server-side component. The server-side component is an executable program running on the Remote Desktop Session Host (RD Session Host) server. The client-side component is a DLL that must be loaded into memory on the client computer when the Remote Desktop Connection (RDC) client program runs.
Virtual channels can add functional enhancements to a Remote Desktop Connection (RDC) client, independent of the RDP protocol. With virtual channel support, new features can be added without having to update the client or server software, or the RDP protocol."

So, virtual channels are just a way of how two endpoints – a client and a server programs, for instance – can connect to each other independently of the lower-layer protocol. In Remote Desktop Services the protocol is RDP, but it can be any other on the assumption that it would provide similar capabilities.

Writing Plugins to rdesktop: Using OOP Patch

As it was mentioned above, you can always just modify rdesktop sources to add or change the needed functionality. There's another way, though – if you don't want to open your changed code to everybody, you can create a separate program that will work as an rdesktop add-in.

There is a patch that makes the virtual channel capability in rdesktop visible to the third parties – i.e., make it possible to create and work with additional virtual channels which handlers are implemented as separate programs. The patch is mainly written by Simon Guerrero. You can get the patch here: Sourceforge.net (the detailed description on the page is outdated - it concerns the old version of the patch, and doesn't reflect its current state. It is just useless). After being upgraded with this patch, rdesktop gets an additional “redirection (-r)” parameter - '-r addin'. The full format of the parameter is:

-r  addin:<channelname>:</path/to/executable>[:arg1[:arg2:]...]

where:

<channelname>  - name of the desired virtual channel;
</path/to/executable>  - path to the VC handler;
[:arg1[:arg2:]...]  - optional parameters passed to the handler by rdesktop.

A few words about the VC handler. When rdesktop creates the handler process and the corresponding virtual channel, it connects the VC output to the process's standard input (stdin), and vice versa – it's standard output (stdout) is connected to the VC's input. The optional parameters are passed to the process as command-line parameters. So, the only thing the handler should do is to read incoming VC data from the stdin and to write outgoing VC data to stdout. Very simple and clear scheme; below it is described in more detail.

From Principles to Code

Okay, this is how it works. The code is not that elegant, but it works and does what is needed. So, let's take a look:

Client Part: Plugin

When plugin starts, it knows that it has been run by rdesktop, and its stdout and stdin are connected to the virtual channel input and output. So plugin just runs an endless loop in which it reads data from the VC and sends some data in response when it's needed. It also sets a SIGUSR1 signal handler, so that rdesktop can terminate plugin task correctly. When rdesktop will disconnect from the remote computer, it will send SIGUSR1 to all plugins, and plugins on receiving SIGUSR1 should stop working:

static int g_end_flag = 0;
// rdesktop sends us a close event by sending  sigusr1
  void sigusr1_handler(int signum)
  {
  g_end_flag = 1;
  }
// we're launched by rdesktop with the following  parameters:
// 1) our ends of read and write pipes that  connects us to rdesktop
//    are  passed as stdin and stdout;
// 2) all parameters are passed via argv[]
  int main(int argc, char **argv)
  {
  char  *data = NULL;
  unsigned  long datalen = 0;
  int  pipe_to_read = -1;
  int  pipe_to_write = -1;
  int i;

  // set  up the SIGUSR1 handler
  struct  sigaction sa;
  sa.sa_handler = sigusr1_handler;
  sigaction(SIGUSR1, &sa, NULL);

  pipe_to_write = dup(STDOUT_FILENO);
  pipe_to_read = dup(STDIN_FILENO);

  while  (!g_end_flag)
  {
     ssize_t bytes_read = read(pipe_to_read, &datalen, sizeof(unsigned  long));
     if  (g_end_flag)
          break;
     if  (bytes_read <= 0)
     {
          perror("pipe  read");
          break;
     }

      data  = malloc (datalen);

      ssize_t all_read = 0;
      do
      {
          bytes_read = read(pipe_to_read, data + all_read, datalen - all_read);
          all_read += bytes_read;
      }
      while (bytes_read > 0 && all_read < datalen &&  !g_end_flag);

     // just send the received data back
     if  (bytes_read > 0)
     {
         write(pipe_to_write,  &datalen, sizeof(unsigned long));
         write(pipe_to_write, data, datalen);
     }

     free(data);
     data  = NULL;
  }

  end:

  if (data  != NULL)
      free(data);
  close(pipe_to_read);
  close(pipe_to_write);

  return  0;
  }

Client Part: rdesktop

When rdesktop finds an '-r addin' parameter,

case 'r':
if (str_startswith(optarg,  "addin"))
{
it initializes the add-in, and add it to the  list of add-ins:
init_external_addin(addin_name,  addin_path, p, &addin_data[addin_count]);
if  (addin_data[addin_count].pid != 0)
{
       addin_count++;
}

In the add-in init function rdesktop prepares add-in parameters, creates its process and connects it to the pipes:

void init_external_addin(char *addin_name, char *addin_path, char *args, 
ADDIN_DATA *addin_data)
{
	char *p;
	char *current_arg;
	char *argv[256];
	char argv_buffer[256][256];
	int i;
	int readpipe[2],writepipe[2];
	pid_t child;

	/* Initialize addin structure */
	memset(addin_data, 0, sizeof(ADDIN_DATA));
	/* Go through the list of args, adding each one to argv */
	argv[0] = addin_path;
	i = 1;
	p=current_arg=args;
	while (current_arg != 0 && current_arg[0] != "\0")
	{
		p=next_arg(p, ":");;
		if (p != 0 && *p != "\0")
			*(p - 1) = "\0";
		strcpy(argv_buffer[i], current_arg);
		argv[i]=argv_buffer[i];
		i++;
		current_arg=p;
	}
	argv[i] = NULL;


	/* Create pipes */
	if (pipe(readpipe) < 0 || pipe(writepipe) < 0)
	{
		perror("pipes for addin");
		return;
	}

	/* Fork process */
	if ((child = fork()) < 0)
	{
		perror("fork for addin");
		return;
	}

	/* Child */
	if (child == 0)
	{
		/* Set stdin and stdout of child to relevant pipe ends */
		dup2(writepipe[0],0);
		dup2(readpipe[1],1);

		/* Close all fds as they are not needed now */
		close(readpipe[0]);
		close(readpipe[1]);
		close(writepipe[0]);
		close(writepipe[1]);
		execvp((char *)argv[0], (char **)argv);
		perror("Error executing child");
		_exit(128);
	}
	else
	{
		strcpy(addin_data->name, addin_name);
		/* Close child end fd"s */
		close(readpipe[1]);
		close(writepipe[0]);
		addin_data->pipe_read=readpipe[0];
		addin_data->pipe_write=writepipe[1];
		addin_data->vchannel=channel_register(addin_name,
						CHANNEL_OPTION_INITIALIZED |
						CHANNEL_OPTION_ENCRYPT_RDP |
						CHANNEL_OPTION_COMPRESS_RDP,
						addin_callback);
		if (!addin_data->vchannel)
		{
			perror("Channel register failed");
			return;
		}
		else
			addin_data->pid=child;
	}
}

The addin_callback() function is called whenever some data is received from the add-in VC:

/* Generic callback for delivering data to third party add-ins */
void addin_callback(STREAM s, char *name)
{
	pid_t pid;
	int pipe_read;
	int pipe_write;
	uint32 blocksize;

	/* s->p is the start and s->end is the end plus 1 */
	blocksize = s->end - s->p;

	/* look up for the add-in by the VC name */
	lookup_addin(name, &pid, &pipe_read, &pipe_write);
	if (!pid)
		perror("Can"t locate addin");
	else
	{
		/* Prepend the block with the block size so that the
                   add-in can identify blocks */
		write(pipe_write, &blocksize, sizeof(uint32));
		write(pipe_write, s->p, blocksize);
	}
}

Data from add-in is read by adding the add-in pipe end to the set of file descriptors:

/* Add the add-in pipes to the set of file descriptors */
void addin_add_fds(int *n, fd_set * rfds)
{
	extern ADDIN_DATA addin_data[];
	extern int addin_count;

	int i;

	for (i = 0; i < addin_count; i++)
	{
		FD_SET(addin_data[i].pipe_read, rfds);
		*n = MAX(*n, addin_data[i].pipe_read);
	}
}

and then select()"ing with the set:

select(n, &rfds, &wfds, NULL, &tv);

The descriptors are checked in an endless loop.

/* Check the add-in pipes for data to write */
void addin_check_fds(fd_set * rfds)
{
	extern ADDIN_DATA addin_data[];
	extern int addin_count;

	int i;
	char buffer[1024];
	ssize_t bytes_read;
	STREAM s;

	for (i = 0; i < addin_count; i++)
	{
		if (FD_ISSET(addin_data[i].pipe_read, rfds))
		{
			bytes_read = read(addin_data[i].pipe_read, buffer, 1024);
			if (bytes_read > 0)
			{
				/* write to appropriate vc */
				s = channel_init(addin_data[i].vchannel, bytes_read);
				memcpy(s->p, buffer, bytes_read);
				s->p += bytes_read;
				s->end = s->p;

				channel_send(s, addin_data[i].vchannel);
			}
 		}
 	}
 }

Server Part

On the server side, you should open a corresponding virtual channel and wait for the request from the client. You can find an example on the patch page.

The End

Okay, that is all. Hope this information was useful. You can use this method not only for rdesktop, but for other programs as well – every time when you want to write a closed-source add-in to some program whose code you can modify.

So, good luck!

History

• 1^st December, 2009: Initial post