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. 

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.
1	astrand	1199	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	ossman_	1232	CREATE,<SERIAL>,<ID>,<GRPID>,<PARENT>,<FLAGS>
57	astrand	1199
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	ossman_	1232	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	astrand	1199	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	ossman_	1232	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	astrand	1199	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.
133
134			STATE
135			-----
136
137			Changes the window's state and/or title.
138
139			Syntax:
140			STATE,<SERIAL>,<ID>,<STATE>,<FLAGS>
141
142			State can have one of three values:
143			0 : "Normal" window.
144			1 : Minimized.
145			2 : Maximized.
146
147			The initial STATE for a window will always be preceeded by one CREATE and one
148			POSITION. Optionally, a TITLE may also be sent before the first STATE.
149
150			DEBUG
151			-----
152
153			Debug output from the server component.
154
155			Syntax:
156			DEBUG,<SERIAL>,<STRING>
157
158			Used for debugging.
159
160			SYNCBEGIN
161			---------
162
163			Indicates that a synchronisation has begun.
164
165			Syntax:
166			SYNCBEGIN,<SERIAL>,<FLAGS>
167
168			Sent when the server starts a synchronisation. The client should flush all
169			information at this point.
170
171			SYNCEND
172			-------
173
174			Indicates that a synchronisation is complete.
175
176			Syntac:
177			SYNCEND,<SERIAL>,<FLAGS>
178
179			Sent when the last message that is part of the synchronisation has been sent.
180			This may be followed by duplicate messages and/or messages referring invalid
181			windows that were queued up during the synchronisation.
182
183			HELLO
184			-----
185
186			Initial message sent by server.
187
188			Syntax:
189			HELLO,<SERIAL>,<FLAGS>
190
191			The server starts each connection by sending this message. Normally the client
192			will react by sending a SYNC back to the server.
193
194			Flags:
195			0x0001 : This is a reconnect to an existing session.
196			0x0002 : The desktop is currently hidden (see HIDE).
197
198			ACK
199			---
200
201			Acknowledgement of a request to manipulate a window.
202
203			Syntax:
204			ACK,<SERIAL>,<ACKSERIAL>
205
206			Whenever one of the commands POSITION, ZCHANGE, STATE or FOCUS is executed on
207			the server, the server will send an ACK back to the client. The purpose of this
208			is to inform the client of when the operation was actually performed, allowing
209			high latencies in the channel.
210
211			HIDE
212			----
213
214			The desktop has become hidden on the server.
215
216			Syntax:
217			HIDE,<SERIAL>,<FLAGS>
218
219			This message is sent when the desktop on the server is obscured by something
220			that cannot be tracked. The client should remove all windows and display the
221			entire desktop, allowing the user to handle whatever is blocking the view.
222
223			Note that updates to windows will still be sent as the windows still exist on
224			the server, they are merely not visible.
225
226			UNHIDE
227			------
228
229			The desktop has been restored on the server.
230
231			Syntax:
232			UNHIDE,<SERIAL>,<FLAGS>
233
234			This message is sent some time after a HIDE, indicating that the windowed view
235			has been restored. If the client has dropped all information about windows then
236			it can send a SYNC to re-enumerate them.
237
238	ossman_	1413	SETICON
239			-------
240
241			Sets an icon for a window.
242
243			Syntax:
244			SETICON,<SERIAL>,<ID>,<CHUNK>,<FORMAT>,<WIDTH>,<HEIGHT>,<DATA>
245
246			This message is sent when a window is initially created and at any time when
247			the application modifies its icon.
248
249			A window can have multiple icons, but only one of a given format and size. A
250			SETICON received for an already existing format and size is expected to over-
251			write that icon.
252
253			Since icons can potentially be very large, it can easily overflow the line
254			limitation in the protocol. To handle this, multiple SETICON will be issued
255			with an ever increasing chunk number.
256
257			The initial chunk is 0 (zero) and all chunks must be sent in order. Multiple
258			SETICON sets for the same window may not interleave. SETICON sets for
259			different windows may interleave though.
260
261			Formats:
262			RGBA : Four bytes of data per pixel, representing red, green, blue and
263			alpha, in that order.
264
265			Data is the raw icon data written in hex (e.g. 3fab32...). Chunks must be
266			divided on a whole byte boundary. Case is not specified.
267
268			DELICON
269			-------
270
271			Removes an icon for a window.
272
273			Syntax:
274			DELICON,<SERIAL>,<ID>,<FORMAT>,<WIDTH>,<HEIGHT>
275
276			Removes the icon of a window matching the given format and size, previously
277			set with SETICON.
278
279			This command may not be interleaved with a SETICON set.
280
281	astrand	1199	Client to Server Operations
282			===========================
283
284			SYNC
285			----
286
287			Request a synchronisation of window information.
288
289			Syntax:
290			SYNC,<SERIAL>,<FLAGS>
291
292			For each window, the server will send CREATE, POSITION and STATE, in that
293			order, just as if the window was created. Note that a TITLE may also,
294			optionally, be sent before the STATE.
295
296			POSITION
297			--------
298
299			Identical to the command sent from server to client.
300
301			TITLE
302			-----
303
304			Identical to the command sent from server to client.
305
306			ZCHANGE
307			-------
308
309			Identical to the command sent from server to client.
310
311			STATE
312			-----
313
314			Identical to the command sent from server to client.
315
316			FOCUS
317			-----
318
319			Sets which window has input focus.
320
321			Syntax:
322			FOCUS,<SERIAL>,<ID>,<FLAGS>
323
324			Changes which window that will recieve the keyboard events. Note that this
325			might cause the window to change z order.