rdesktop/doc/seamlessrdp-channel.txt

TODO
----

* Command for executing new programs.

* Commands for changing z order and focus.

* Command for transferring icon.

* 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.

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			* Command for transferring icon.
9
10			* Think about protocol version management
11
12			* Try to assure that messages aren't repeated or are sent for hidden windows.
13
14			Overview
15			========
16
17			The protocol is a line based protocol following this simple syntax:
18
19			OPERATION,SERIAL[,ARG1[,ARG2,[...]]]
20
21			Each operation will have an increasing serial number. The initial value is
22			implementation defined.
23
24			The goal is to have a generic protocol that can be used for other display
25			systems (e.g. VNC) as well.
26
27			One line may not exceed 1024 bytes, including newline.
28
29			The protocol has no concept of hidden or unmapped windows. A window does not
30			exist unless it is visible. Note that a minimized window is an exception to
31			this rule.
32
33			The protocol has no way of indicating failure, meaning that all commands are
34			expected to succeed. If a command fails, the receiving end must send a
35			corresponding command back, indicating the actual state.
36
37			Data types
38			==========
39			Window ID are written in hex, like 0x4321.
40
41			Window positions can be negative. This happens when a window is moved
42			outside the desktop.
43
44			All integers fit inside 32 bits.
45
46			Strings are sent in UTF-8 and do not contain any characters less than 0x20 or
47			the character , (comma).
48
49			Server to Client Operations
50			===========================
51
52			CREATE
53			------
54
55			Allocate structures for a new window.
56
57			Syntax:
58	ossman_	1232	CREATE,<SERIAL>,<ID>,<GRPID>,<PARENT>,<FLAGS>
59	astrand	1199
60			Indicates that a window has appeared on the server. If PARENT is non-zero then
61			the new window is a child of that window (it's transient for it). The special
62			value 0xFFFFFFFF for PARENT means that the window is a popup window without a
63			parent. It's commonly used for splash screens, tool tips and context menus.
64
65	ossman_	1232	The group id identifies a set of windows that belong together. It is currently
66			only used for modal windows and DESTROYGRP.
67
68			Flags:
69			0x0001 : Create a window that's modal with regard to the other windows
70			in the same group.
71
72	astrand	1199	Note that very little information is included in this message. Things like
73			title and state will come in subsequent messages. This message should only
74			be used to allocate data structures for the new window.
75
76			DESTROY
77			-------
78
79			Remove a window.
80
81			Syntax:
82			DESTROY,<SERIAL>,<ID>,<FLAGS>
83
84			Remove the window and deallocate all associated structures.
85
86	ossman_	1232	DESTROYGRP
87			----------
88
89			Destroy an entire group of windows.
90
91			Syntax:
92			DESTROYGRP,<SERIAL>,<GRPID>,<FLAGS>
93
94			Every window that belongs to the group GRPID should be destroyed as if they
95			each got a DESTROY message.
96
97	astrand	1199	POSITION
98			--------
99
100			Move and/or resize a window.
101
102			Syntax:
103			POSITION,<SERIAL>,<ID>,<X>,<Y>,<WIDTH>,<HEIGHT>,<FLAGS>
104
105			If the window isn't visible yet (because a
106			STATE hasn't been set or because it's minimized), you must store the position
107			and size. A new POSITION is not guaranteed to be sent when the window changes
108			state.
109
110			TITLE
111			-----
112
113			Sets a window title.
114
115			Syntax:
116			TITLE,<SERIAL>,<ID>,<TITLE>,<FLAGS>
117
118			The text is guaranteed to be stripped of control characters (< 0x20).
119
120			Note that this has the same requirement as POSITION, that the title needs to
121			be stored for newly created windows until a STATE is sent. It is however not
122			guaranteed that a TITLE will be sent before the first STATE.
123
124
125			ZCHANGE
126			-------
127
128			The window moved in z order.
129
130			Syntax:
131			ZCHANGE,<SERIAL>,<ID>,<BEHIND>,<FLAGS>
132
133			The window with the id ID is behind the window with the id BEHIND. If
134			BEHIND is 0, then this window should be brought to the front.
135
136			STATE
137			-----
138
139			Changes the window's state and/or title.
140
141			Syntax:
142			STATE,<SERIAL>,<ID>,<STATE>,<FLAGS>
143
144			State can have one of three values:
145			0 : "Normal" window.
146			1 : Minimized.
147			2 : Maximized.
148
149			The initial STATE for a window will always be preceeded by one CREATE and one
150			POSITION. Optionally, a TITLE may also be sent before the first STATE.
151
152			DEBUG
153			-----
154
155			Debug output from the server component.
156
157			Syntax:
158			DEBUG,<SERIAL>,<STRING>
159
160			Used for debugging.
161
162			SYNCBEGIN
163			---------
164
165			Indicates that a synchronisation has begun.
166
167			Syntax:
168			SYNCBEGIN,<SERIAL>,<FLAGS>
169
170			Sent when the server starts a synchronisation. The client should flush all
171			information at this point.
172
173			SYNCEND
174			-------
175
176			Indicates that a synchronisation is complete.
177
178			Syntac:
179			SYNCEND,<SERIAL>,<FLAGS>
180
181			Sent when the last message that is part of the synchronisation has been sent.
182			This may be followed by duplicate messages and/or messages referring invalid
183			windows that were queued up during the synchronisation.
184
185			HELLO
186			-----
187
188			Initial message sent by server.
189
190			Syntax:
191			HELLO,<SERIAL>,<FLAGS>
192
193			The server starts each connection by sending this message. Normally the client
194			will react by sending a SYNC back to the server.
195
196			Flags:
197			0x0001 : This is a reconnect to an existing session.
198			0x0002 : The desktop is currently hidden (see HIDE).
199
200			ACK
201			---
202
203			Acknowledgement of a request to manipulate a window.
204
205			Syntax:
206			ACK,<SERIAL>,<ACKSERIAL>
207
208			Whenever one of the commands POSITION, ZCHANGE, STATE or FOCUS is executed on
209			the server, the server will send an ACK back to the client. The purpose of this
210			is to inform the client of when the operation was actually performed, allowing
211			high latencies in the channel.
212
213			HIDE
214			----
215
216			The desktop has become hidden on the server.
217
218			Syntax:
219			HIDE,<SERIAL>,<FLAGS>
220
221			This message is sent when the desktop on the server is obscured by something
222			that cannot be tracked. The client should remove all windows and display the
223			entire desktop, allowing the user to handle whatever is blocking the view.
224
225			Note that updates to windows will still be sent as the windows still exist on
226			the server, they are merely not visible.
227
228			UNHIDE
229			------
230
231			The desktop has been restored on the server.
232
233			Syntax:
234			UNHIDE,<SERIAL>,<FLAGS>
235
236			This message is sent some time after a HIDE, indicating that the windowed view
237			has been restored. If the client has dropped all information about windows then
238			it can send a SYNC to re-enumerate them.
239
240			Client to Server Operations
241			===========================
242
243			SYNC
244			----
245
246			Request a synchronisation of window information.
247
248			Syntax:
249			SYNC,<SERIAL>,<FLAGS>
250
251			For each window, the server will send CREATE, POSITION and STATE, in that
252			order, just as if the window was created. Note that a TITLE may also,
253			optionally, be sent before the STATE.
254
255			POSITION
256			--------
257
258			Identical to the command sent from server to client.
259
260			TITLE
261			-----
262
263			Identical to the command sent from server to client.
264
265			ZCHANGE
266			-------
267
268			Identical to the command sent from server to client.
269
270			STATE
271			-----
272
273			Identical to the command sent from server to client.
274
275			FOCUS
276			-----
277
278			Sets which window has input focus.
279
280			Syntax:
281			FOCUS,<SERIAL>,<ID>,<FLAGS>
282
283			Changes which window that will recieve the keyboard events. Note that this
284			might cause the window to change z order.