rdesktop/doc/seamlessrdp-channel.txt

TODO
----

* Command for executing new programs.

* Commands for changing z order and focus.

* Think about protocol version management

* Try to assure that messages aren't repeated or are sent for hidden windows.

Overview
========

The protocol is a line based protocol following this simple syntax:

        OPERATION,SERIAL[,ARG1[,ARG2,[...]]]

Each operation will have an increasing serial number. The initial value is
implementation defined.

The goal is to have a generic protocol that can be used for other display
systems (e.g. VNC) as well.

One line may not exceed 1024 bytes, including newline.

The protocol has no concept of hidden or unmapped windows. A window does not
exist unless it is visible. Note that a minimized window is an exception to
this rule.

The protocol has no way of indicating failure, meaning that all commands are
expected to succeed. If a command fails, the receiving end must send a
corresponding command back, indicating the actual state.

Data types
==========
Window ID are written in hex, like 0x4321. 

Window positions can be negative. This happens when a window is moved
outside the desktop.

All integers fit inside 32 bits.

Strings are sent in UTF-8 and do not contain any characters less than 0x20 or
the character , (comma).

Server to Client Operations
===========================

CREATE
------

Allocate structures for a new window.

Syntax:
        CREATE,<SERIAL>,<ID>,<GRPID>,<PARENT>,<FLAGS>

Indicates that a window has appeared on the server. If PARENT is non-zero then
the new window is a child of that window (it's transient for it). The special
value 0xFFFFFFFF for PARENT means that the window is a popup window without a
parent. It's commonly used for splash screens, tool tips and context menus.

The group id identifies a set of windows that belong together. It is currently
only used for modal windows and DESTROYGRP.

Flags:
        0x0001 : Create a window that's modal with regard to the other windows
                 in the same group.

Note that very little information is included in this message. Things like
title and state will come in subsequent messages. This message should only
be used to allocate data structures for the new window.

DESTROY
-------

Remove a window.

Syntax:
        DESTROY,<SERIAL>,<ID>,<FLAGS>

Remove the window and deallocate all associated structures.

DESTROYGRP
----------

Destroy an entire group of windows.

Syntax:
        DESTROYGRP,<SERIAL>,<GRPID>,<FLAGS>

Every window that belongs to the group GRPID should be destroyed as if they
each got a DESTROY message.

POSITION
--------

Move and/or resize a window.

Syntax:
        POSITION,<SERIAL>,<ID>,<X>,<Y>,<WIDTH>,<HEIGHT>,<FLAGS>

If the window isn't visible yet (because a
STATE hasn't been set or because it's minimized), you must store the position
and size. A new POSITION is not guaranteed to be sent when the window changes
state.

TITLE
-----

Sets a window title.

Syntax:
        TITLE,<SERIAL>,<ID>,<TITLE>,<FLAGS>

The text is guaranteed to be stripped of control characters (< 0x20).

Note that this has the same requirement as POSITION, that the title needs to
be stored for newly created windows until a STATE is sent. It is however not
guaranteed that a TITLE will be sent before the first STATE.


ZCHANGE
-------

The window moved in z order.

Syntax:
        ZCHANGE,<SERIAL>,<ID>,<BEHIND>,<FLAGS>

The window with the id ID is behind the window with the id BEHIND. If
BEHIND is 0, then this window should be brought to the front. The ID
window is the window to be moved, while the BEHIND window is only used
as a reference.


STATE
-----

Changes the window's state and/or title.

Syntax:
        STATE,<SERIAL>,<ID>,<STATE>,<FLAGS>

State can have one of three values:
 0 : "Normal" window.
 1 : Minimized.
 2 : Maximized.

The initial STATE for a window will always be preceeded by one CREATE and one
POSITION. Optionally, a TITLE may also be sent before the first STATE.

DEBUG
-----

Debug output from the server component.

Syntax:
        DEBUG,<SERIAL>,<STRING>

Used for debugging.

SYNCBEGIN
---------

Indicates that a synchronisation has begun.

Syntax:
        SYNCBEGIN,<SERIAL>,<FLAGS>

Sent when the server starts a synchronisation. The client should flush all
information at this point.

SYNCEND
-------

Indicates that a synchronisation is complete.

Syntac:
        SYNCEND,<SERIAL>,<FLAGS>

Sent when the last message that is part of the synchronisation has been sent.
This may be followed by duplicate messages and/or messages referring invalid
windows that were queued up during the synchronisation.

HELLO
-----

Initial message sent by server.

Syntax:
        HELLO,<SERIAL>,<FLAGS>

The server starts each connection by sending this message. Normally the client
will react by sending a SYNC back to the server. 

Flags:
  0x0001 : This is a reconnect to an existing session.
  0x0002 : The desktop is currently hidden (see HIDE).

ACK
---

Acknowledgement of a request to manipulate a window.

Syntax:
        ACK,<SERIAL>,<ACKSERIAL>

Whenever one of the commands POSITION, ZCHANGE, STATE or FOCUS is executed on
the server, the server will send an ACK back to the client. The purpose of this
is to inform the client of when the operation was actually performed, allowing
high latencies in the channel.

HIDE
----

The desktop has become hidden on the server.

Syntax:
        HIDE,<SERIAL>,<FLAGS>

This message is sent when the desktop on the server is obscured by something
that cannot be tracked. The client should remove all windows and display the
entire desktop, allowing the user to handle whatever is blocking the view.

Note that updates to windows will still be sent as the windows still exist on
the server, they are merely not visible.

UNHIDE
------

The desktop has been restored on the server.

Syntax:
        UNHIDE,<SERIAL>,<FLAGS>

This message is sent some time after a HIDE, indicating that the windowed view
has been restored. If the client has dropped all information about windows then
it can send a SYNC to re-enumerate them.

SETICON
-------

Sets an icon for a window.

Syntax:
        SETICON,<SERIAL>,<ID>,<CHUNK>,<FORMAT>,<WIDTH>,<HEIGHT>,<DATA>

This message is sent when a window is initially created and at any time when
the application modifies its icon.

A window can have multiple icons, but only one of a given format and size. A
SETICON received for an already existing format and size is expected to over-
write that icon.

Since icons can potentially be very large, it can easily overflow the line
limitation in the protocol. To handle this, multiple SETICON will be issued
with an ever increasing chunk number.

The initial chunk is 0 (zero) and all chunks must be sent in order. Multiple
SETICON sets for the same window may not interleave. SETICON sets for
different windows may interleave though.

Formats:
  RGBA : Four bytes of data per pixel, representing red, green, blue and
         alpha, in that order.

Data is the raw icon data written in hex (e.g. 3fab32...). Chunks must be
divided on a whole byte boundary. Case is not specified.

DELICON
-------

Removes an icon for a window.

Syntax:
        DELICON,<SERIAL>,<ID>,<FORMAT>,<WIDTH>,<HEIGHT>

Removes the icon of a window matching the given format and size, previously
set with SETICON.

This command may not be interleaved with a SETICON set.

Client to Server Operations
===========================

SYNC
----

Request a synchronisation of window information.

Syntax:
        SYNC,<SERIAL>,<FLAGS>

For each window, the server will send CREATE, POSITION and STATE, in that
order, just as if the window was created. Note that a TITLE may also,
optionally, be sent before the STATE.

POSITION
--------

Identical to the command sent from server to client.

TITLE
-----

Identical to the command sent from server to client.

ZCHANGE
-------

Identical to the command sent from server to client.

STATE
-----

Identical to the command sent from server to client.

FOCUS
-----

Sets which window has input focus.

Syntax:
        FOCUS,<SERIAL>,<ID>,<FLAGS>

Changes which window that will recieve the keyboard events. Note that this
might cause the window to change z order.

DESTROY
-------

Identical to the command sent from server to client.


Test Cases
==========

A list of test cases is found below. These should be verified before
commit, ideally with different window managers (KWin, Metacity,
Blackbox, IceWM etc).


* Start Wordpad. Verify taskbar icon. 

* Resize Wordpad main window. 

* Open "Open Dialog". Resize, bigger than main window. Verify no
  additional task bar icons. Verify that the Open dialog is focused.

* Open File Format box dropdown. Verify that it correctly appears
  outside main window. Verify no additional task bar icons. 

* Abort Open. Select About Wordpad. Verify no additional task bar
  icons. Verify that the About dialog is focused. 

* Open Wordpad Help. Verify task bar icon. 

* Switch between Help and Wordpad window using a X11 taskbar. 

* In Wordpad, right click at the bottom of the document, and verify
  that the menu correctly appears outside the main window. Verify no
  additional task bar icons.

* Click on the New icon. Select Text Document. Verify that the taskbar
  icon is updated.

* Write something. Try the Find dialog (Ctrl-F). Move it outside the
  main window. Verify no task bar icons. 

* Make Wordpad very small and try to use the menus. 


* Start Internet Explorer. 

* Minimize IE using the IE button. Restore. 

* Minimize IE using the taskbar. Restore. 

* Maximize IE using the IE button. Restore. 

* Maximize IE using the taskbar. Restore. 

* Open an additional IE window and verify you can switch between them. 


* Try the menus in Microsoft Office XP, which uses shaded menus. 


* Test transient windows: Run a program (ie Excel) seamlessly and open
  a modal dialog (ie Open). Move the dialog so it partially overlaps
  its parent window. Cover both windows with a third (ie a maximized
  xterm). Click on Excel's taskbar entry to bring it to the front.


* Test topmost windows: Run Task Manager seamlessly
  (...\seamlessrdpshell.exe taskmgr). From Task Manager's File menu,
  select 'New Task (Run)' and run Notepad. Move Notepad so it
  partially overlaps Task Manager. Cover both windows with a native
  window (ie a maximized xterm). Click on Notepad's taskbar entry to
  bring it to the front.


* Test X11 window close: Start Notepad and open the Help
  Browser. Close the Help Browser window on the X11 side using your
  window manager. Verify that rdesktop still runs and that the Notepad
  application window still exists.


* Test window restacking: Run Mozilla Seamonkey and open two separate
  windows. From the first one, select the other one from the windows
  menu. Verify that the other window is brought to the front. Test
  this using both the mouse and the keyboard.
1	TODO
2	----
3
4	* Command for executing new programs.
5
6	* Commands for changing z order and focus.
7
8	* Think about protocol version management
9
10	* Try to assure that messages aren't repeated or are sent for hidden windows.
11
12	Overview
13	========
14
15	The protocol is a line based protocol following this simple syntax:
16
17	OPERATION,SERIAL[,ARG1[,ARG2,[...]]]
18
19	Each operation will have an increasing serial number. The initial value is
20	implementation defined.
21
22	The goal is to have a generic protocol that can be used for other display
23	systems (e.g. VNC) as well.
24
25	One line may not exceed 1024 bytes, including newline.
26
27	The protocol has no concept of hidden or unmapped windows. A window does not
28	exist unless it is visible. Note that a minimized window is an exception to
29	this rule.
30
31	The protocol has no way of indicating failure, meaning that all commands are
32	expected to succeed. If a command fails, the receiving end must send a
33	corresponding command back, indicating the actual state.
34
35	Data types
36	==========
37	Window ID are written in hex, like 0x4321.
38
39	Window positions can be negative. This happens when a window is moved
40	outside the desktop.
41
42	All integers fit inside 32 bits.
43
44	Strings are sent in UTF-8 and do not contain any characters less than 0x20 or
45	the character , (comma).
46
47	Server to Client Operations
48	===========================
49
50	CREATE
51	------
52
53	Allocate structures for a new window.
54
55	Syntax:
56	CREATE,<SERIAL>,<ID>,<GRPID>,<PARENT>,<FLAGS>
57
58	Indicates that a window has appeared on the server. If PARENT is non-zero then
59	the new window is a child of that window (it's transient for it). The special
60	value 0xFFFFFFFF for PARENT means that the window is a popup window without a
61	parent. It's commonly used for splash screens, tool tips and context menus.
62
63	The group id identifies a set of windows that belong together. It is currently
64	only used for modal windows and DESTROYGRP.
65
66	Flags:
67	0x0001 : Create a window that's modal with regard to the other windows
68	in the same group.
69
70	Note that very little information is included in this message. Things like
71	title and state will come in subsequent messages. This message should only
72	be used to allocate data structures for the new window.
73
74	DESTROY
75	-------
76
77	Remove a window.
78
79	Syntax:
80	DESTROY,<SERIAL>,<ID>,<FLAGS>
81
82	Remove the window and deallocate all associated structures.
83
84	DESTROYGRP
85	----------
86
87	Destroy an entire group of windows.
88
89	Syntax:
90	DESTROYGRP,<SERIAL>,<GRPID>,<FLAGS>
91
92	Every window that belongs to the group GRPID should be destroyed as if they
93	each got a DESTROY message.
94
95	POSITION
96	--------
97
98	Move and/or resize a window.
99
100	Syntax:
101	POSITION,<SERIAL>,<ID>,<X>,<Y>,<WIDTH>,<HEIGHT>,<FLAGS>
102
103	If the window isn't visible yet (because a
104	STATE hasn't been set or because it's minimized), you must store the position
105	and size. A new POSITION is not guaranteed to be sent when the window changes
106	state.
107
108	TITLE
109	-----
110
111	Sets a window title.
112
113	Syntax:
114	TITLE,<SERIAL>,<ID>,<TITLE>,<FLAGS>
115
116	The text is guaranteed to be stripped of control characters (< 0x20).
117
118	Note that this has the same requirement as POSITION, that the title needs to
119	be stored for newly created windows until a STATE is sent. It is however not
120	guaranteed that a TITLE will be sent before the first STATE.
121
122
123	ZCHANGE
124	-------
125
126	The window moved in z order.
127
128	Syntax:
129	ZCHANGE,<SERIAL>,<ID>,<BEHIND>,<FLAGS>
130
131	The window with the id ID is behind the window with the id BEHIND. If
132	BEHIND is 0, then this window should be brought to the front. The ID
133	window is the window to be moved, while the BEHIND window is only used
134	as a reference.
135
136
137	STATE
138	-----
139
140	Changes the window's state and/or title.
141
142	Syntax:
143	STATE,<SERIAL>,<ID>,<STATE>,<FLAGS>
144
145	State can have one of three values:
146	0 : "Normal" window.
147	1 : Minimized.
148	2 : Maximized.
149
150	The initial STATE for a window will always be preceeded by one CREATE and one
151	POSITION. Optionally, a TITLE may also be sent before the first STATE.
152
153	DEBUG
154	-----
155
156	Debug output from the server component.
157
158	Syntax:
159	DEBUG,<SERIAL>,<STRING>
160
161	Used for debugging.
162
163	SYNCBEGIN
164	---------
165
166	Indicates that a synchronisation has begun.
167
168	Syntax:
169	SYNCBEGIN,<SERIAL>,<FLAGS>
170
171	Sent when the server starts a synchronisation. The client should flush all
172	information at this point.
173
174	SYNCEND
175	-------
176
177	Indicates that a synchronisation is complete.
178
179	Syntac:
180	SYNCEND,<SERIAL>,<FLAGS>
181
182	Sent when the last message that is part of the synchronisation has been sent.
183	This may be followed by duplicate messages and/or messages referring invalid
184	windows that were queued up during the synchronisation.
185
186	HELLO
187	-----
188
189	Initial message sent by server.
190
191	Syntax:
192	HELLO,<SERIAL>,<FLAGS>
193
194	The server starts each connection by sending this message. Normally the client
195	will react by sending a SYNC back to the server.
196
197	Flags:
198	0x0001 : This is a reconnect to an existing session.
199	0x0002 : The desktop is currently hidden (see HIDE).
200
201	ACK
202	---
203
204	Acknowledgement of a request to manipulate a window.
205
206	Syntax:
207	ACK,<SERIAL>,<ACKSERIAL>
208
209	Whenever one of the commands POSITION, ZCHANGE, STATE or FOCUS is executed on
210	the server, the server will send an ACK back to the client. The purpose of this
211	is to inform the client of when the operation was actually performed, allowing
212	high latencies in the channel.
213
214	HIDE
215	----
216
217	The desktop has become hidden on the server.
218
219	Syntax:
220	HIDE,<SERIAL>,<FLAGS>
221
222	This message is sent when the desktop on the server is obscured by something
223	that cannot be tracked. The client should remove all windows and display the
224	entire desktop, allowing the user to handle whatever is blocking the view.
225
226	Note that updates to windows will still be sent as the windows still exist on
227	the server, they are merely not visible.
228
229	UNHIDE
230	------
231
232	The desktop has been restored on the server.
233
234	Syntax:
235	UNHIDE,<SERIAL>,<FLAGS>
236
237	This message is sent some time after a HIDE, indicating that the windowed view
238	has been restored. If the client has dropped all information about windows then
239	it can send a SYNC to re-enumerate them.
240
241	SETICON
242	-------
243
244	Sets an icon for a window.
245
246	Syntax:
247	SETICON,<SERIAL>,<ID>,<CHUNK>,<FORMAT>,<WIDTH>,<HEIGHT>,<DATA>
248
249	This message is sent when a window is initially created and at any time when
250	the application modifies its icon.
251
252	A window can have multiple icons, but only one of a given format and size. A
253	SETICON received for an already existing format and size is expected to over-
254	write that icon.
255
256	Since icons can potentially be very large, it can easily overflow the line
257	limitation in the protocol. To handle this, multiple SETICON will be issued
258	with an ever increasing chunk number.
259
260	The initial chunk is 0 (zero) and all chunks must be sent in order. Multiple
261	SETICON sets for the same window may not interleave. SETICON sets for
262	different windows may interleave though.
263
264	Formats:
265	RGBA : Four bytes of data per pixel, representing red, green, blue and
266	alpha, in that order.
267
268	Data is the raw icon data written in hex (e.g. 3fab32...). Chunks must be
269	divided on a whole byte boundary. Case is not specified.
270
271	DELICON
272	-------
273
274	Removes an icon for a window.
275
276	Syntax:
277	DELICON,<SERIAL>,<ID>,<FORMAT>,<WIDTH>,<HEIGHT>
278
279	Removes the icon of a window matching the given format and size, previously
280	set with SETICON.
281
282	This command may not be interleaved with a SETICON set.
283
284	Client to Server Operations
285	===========================
286
287	SYNC
288	----
289
290	Request a synchronisation of window information.
291
292	Syntax:
293	SYNC,<SERIAL>,<FLAGS>
294
295	For each window, the server will send CREATE, POSITION and STATE, in that
296	order, just as if the window was created. Note that a TITLE may also,
297	optionally, be sent before the STATE.
298
299	POSITION
300	--------
301
302	Identical to the command sent from server to client.
303
304	TITLE
305	-----
306
307	Identical to the command sent from server to client.
308
309	ZCHANGE
310	-------
311
312	Identical to the command sent from server to client.
313
314	STATE
315	-----
316
317	Identical to the command sent from server to client.
318
319	FOCUS
320	-----
321
322	Sets which window has input focus.
323
324	Syntax:
325	FOCUS,<SERIAL>,<ID>,<FLAGS>
326
327	Changes which window that will recieve the keyboard events. Note that this
328	might cause the window to change z order.
329
330	DESTROY
331	-------
332
333	Identical to the command sent from server to client.
334
335
336	Test Cases
337	==========
338
339	A list of test cases is found below. These should be verified before
340	commit, ideally with different window managers (KWin, Metacity,
341	Blackbox, IceWM etc).
342
343
344	* Start Wordpad. Verify taskbar icon.
345
346	* Resize Wordpad main window.
347
348	* Open "Open Dialog". Resize, bigger than main window. Verify no
349	additional task bar icons. Verify that the Open dialog is focused.
350
351	* Open File Format box dropdown. Verify that it correctly appears
352	outside main window. Verify no additional task bar icons.
353
354	* Abort Open. Select About Wordpad. Verify no additional task bar
355	icons. Verify that the About dialog is focused.
356
357	* Open Wordpad Help. Verify task bar icon.
358
359	* Switch between Help and Wordpad window using a X11 taskbar.
360
361	* In Wordpad, right click at the bottom of the document, and verify
362	that the menu correctly appears outside the main window. Verify no
363	additional task bar icons.
364
365	* Click on the New icon. Select Text Document. Verify that the taskbar
366	icon is updated.
367
368	* Write something. Try the Find dialog (Ctrl-F). Move it outside the
369	main window. Verify no task bar icons.
370
371	* Make Wordpad very small and try to use the menus.
372
373
374	* Start Internet Explorer.
375
376	* Minimize IE using the IE button. Restore.
377
378	* Minimize IE using the taskbar. Restore.
379
380	* Maximize IE using the IE button. Restore.
381
382	* Maximize IE using the taskbar. Restore.
383
384	* Open an additional IE window and verify you can switch between them.
385
386
387	* Try the menus in Microsoft Office XP, which uses shaded menus.
388
389
390	* Test transient windows: Run a program (ie Excel) seamlessly and open
391	a modal dialog (ie Open). Move the dialog so it partially overlaps
392	its parent window. Cover both windows with a third (ie a maximized
393	xterm). Click on Excel's taskbar entry to bring it to the front.
394
395
396	* Test topmost windows: Run Task Manager seamlessly
397	(...\seamlessrdpshell.exe taskmgr). From Task Manager's File menu,
398	select 'New Task (Run)' and run Notepad. Move Notepad so it
399	partially overlaps Task Manager. Cover both windows with a native
400	window (ie a maximized xterm). Click on Notepad's taskbar entry to
401	bring it to the front.
402
403
404	* Test X11 window close: Start Notepad and open the Help
405	Browser. Close the Help Browser window on the X11 side using your
406	window manager. Verify that rdesktop still runs and that the Notepad
407	application window still exists.
408
409
410	* Test window restacking: Run Mozilla Seamonkey and open two separate
411	windows. From the first one, select the other one from the windows
412	menu. Verify that the other window is brought to the front. Test
413	this using both the mouse and the keyboard.