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

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.

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	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	CREATE,<SERIAL>,<ID>,<PARENT>,<FLAGS>
59
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	Note that very little information is included in this message. Things like
66	title and state will come in subsequent messages. This message should only
67	be used to allocate data structures for the new window.
68
69	DESTROY
70	-------
71
72	Remove a window.
73
74	Syntax:
75	DESTROY,<SERIAL>,<ID>,<FLAGS>
76
77	Remove the window and deallocate all associated structures.
78
79	POSITION
80	--------
81
82	Move and/or resize a window.
83
84	Syntax:
85	POSITION,<SERIAL>,<ID>,<X>,<Y>,<WIDTH>,<HEIGHT>,<FLAGS>
86
87	If the window isn't visible yet (because a
88	STATE hasn't been set or because it's minimized), you must store the position
89	and size. A new POSITION is not guaranteed to be sent when the window changes
90	state.
91
92	TITLE
93	-----
94
95	Sets a window title.
96
97	Syntax:
98	TITLE,<SERIAL>,<ID>,<TITLE>,<FLAGS>
99
100	The text is guaranteed to be stripped of control characters (< 0x20).
101
102	Note that this has the same requirement as POSITION, that the title needs to
103	be stored for newly created windows until a STATE is sent. It is however not
104	guaranteed that a TITLE will be sent before the first STATE.
105
106
107	ZCHANGE
108	-------
109
110	The window moved in z order.
111
112	Syntax:
113	ZCHANGE,<SERIAL>,<ID>,<BEHIND>,<FLAGS>
114
115	The window with the id ID is behind the window with the id BEHIND. If
116	BEHIND is 0, then this window should be brought to the front.
117
118	STATE
119	-----
120
121	Changes the window's state and/or title.
122
123	Syntax:
124	STATE,<SERIAL>,<ID>,<STATE>,<FLAGS>
125
126	State can have one of three values:
127	0 : "Normal" window.
128	1 : Minimized.
129	2 : Maximized.
130
131	The initial STATE for a window will always be preceeded by one CREATE and one
132	POSITION. Optionally, a TITLE may also be sent before the first STATE.
133
134	DEBUG
135	-----
136
137	Debug output from the server component.
138
139	Syntax:
140	DEBUG,<SERIAL>,<STRING>
141
142	Used for debugging.
143
144	SYNCBEGIN
145	---------
146
147	Indicates that a synchronisation has begun.
148
149	Syntax:
150	SYNCBEGIN,<SERIAL>,<FLAGS>
151
152	Sent when the server starts a synchronisation. The client should flush all
153	information at this point.
154
155	SYNCEND
156	-------
157
158	Indicates that a synchronisation is complete.
159
160	Syntac:
161	SYNCEND,<SERIAL>,<FLAGS>
162
163	Sent when the last message that is part of the synchronisation has been sent.
164	This may be followed by duplicate messages and/or messages referring invalid
165	windows that were queued up during the synchronisation.
166
167	HELLO
168	-----
169
170	Initial message sent by server.
171
172	Syntax:
173	HELLO,<SERIAL>,<FLAGS>
174
175	The server starts each connection by sending this message. Normally the client
176	will react by sending a SYNC back to the server.
177
178	Flags:
179	0x0001 : This is a reconnect to an existing session.
180	0x0002 : The desktop is currently hidden (see HIDE).
181
182	ACK
183	---
184
185	Acknowledgement of a request to manipulate a window.
186
187	Syntax:
188	ACK,<SERIAL>,<ACKSERIAL>
189
190	Whenever one of the commands POSITION, ZCHANGE, STATE or FOCUS is executed on
191	the server, the server will send an ACK back to the client. The purpose of this
192	is to inform the client of when the operation was actually performed, allowing
193	high latencies in the channel.
194
195	HIDE
196	----
197
198	The desktop has become hidden on the server.
199
200	Syntax:
201	HIDE,<SERIAL>,<FLAGS>
202
203	This message is sent when the desktop on the server is obscured by something
204	that cannot be tracked. The client should remove all windows and display the
205	entire desktop, allowing the user to handle whatever is blocking the view.
206
207	Note that updates to windows will still be sent as the windows still exist on
208	the server, they are merely not visible.
209
210	UNHIDE
211	------
212
213	The desktop has been restored on the server.
214
215	Syntax:
216	UNHIDE,<SERIAL>,<FLAGS>
217
218	This message is sent some time after a HIDE, indicating that the windowed view
219	has been restored. If the client has dropped all information about windows then
220	it can send a SYNC to re-enumerate them.
221
222	Client to Server Operations
223	===========================
224
225	SYNC
226	----
227
228	Request a synchronisation of window information.
229
230	Syntax:
231	SYNC,<SERIAL>,<FLAGS>
232
233	For each window, the server will send CREATE, POSITION and STATE, in that
234	order, just as if the window was created. Note that a TITLE may also,
235	optionally, be sent before the STATE.
236
237	POSITION
238	--------
239
240	Identical to the command sent from server to client.
241
242	TITLE
243	-----
244
245	Identical to the command sent from server to client.
246
247	ZCHANGE
248	-------
249
250	Identical to the command sent from server to client.
251
252	STATE
253	-----
254
255	Identical to the command sent from server to client.
256
257	FOCUS
258	-----
259
260	Sets which window has input focus.
261
262	Syntax:
263	FOCUS,<SERIAL>,<ID>,<FLAGS>
264
265	Changes which window that will recieve the keyboard events. Note that this
266	might cause the window to change z order.