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[,ARG1[,ARG2,[...]]]

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.

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,<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,<ID>,<FLAGS>

Remove the window and deallocate all associated structures.

POSITION
--------

Move and/or resize a window.

Syntax:
        POSITION,<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,<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,<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,<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,<STRING>

Used for debugging.

SYNCBEGIN
---------

Indicates that a synchronisation has begun.

Syntax:
        SYNCBEGIN,<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,<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.

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

SYNC
----

Request a synchronisation of window information.

Syntax:
        SYNC,<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,<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[,ARG1[,ARG2,[...]]]
20
21	The goal is to have a generic protocol that can be used for other display
22	systems (e.g. VNC) as well.
23
24	One line may not exceed 1024 bytes, including newline.
25
26	The protocol has no concept of hidden or unmapped windows. A window does not
27	exist unless it is visible. Note that a minimized window is an exception to
28	this rule.
29
30	Data types
31	==========
32	Window ID are written in hex, like 0x4321.
33
34	Window positions can be negative. This happens when a window is moved
35	outside the desktop.
36
37	All integers fit inside 32 bits.
38
39	Strings are sent in UTF-8 and do not contain any characters less than 0x20 or
40	the character , (comma).
41
42	Server to Client Operations
43	===========================
44
45	CREATE
46	------
47
48	Allocate structures for a new window.
49
50	Syntax:
51	CREATE,<ID>,<PARENT>,<FLAGS>
52
53	Indicates that a window has appeared on the server. If PARENT is non-zero then
54	the new window is a child of that window (it's transient for it). The special
55	value 0xFFFFFFFF for PARENT means that the window is a popup window without a
56	parent. It's commonly used for splash screens, tool tips and context menus.
57
58	Note that very little information is included in this message. Things like
59	title and state will come in subsequent messages. This message should only
60	be used to allocate data structures for the new window.
61
62	DESTROY
63	-------
64
65	Remove a window.
66
67	Syntax:
68	DESTROY,<ID>,<FLAGS>
69
70	Remove the window and deallocate all associated structures.
71
72	POSITION
73	--------
74
75	Move and/or resize a window.
76
77	Syntax:
78	POSITION,<ID>,<X>,<Y>,<WIDTH>,<HEIGHT>,<FLAGS>
79
80	If the window isn't visible yet (because a
81	STATE hasn't been set or because it's minimized), you must store the position
82	and size. A new POSITION is not guaranteed to be sent when the window changes
83	state.
84
85	TITLE
86	-----
87
88	Sets a window title.
89
90	Syntax:
91	TITLE,<ID>,<TITLE>,<FLAGS>
92
93	The text is guaranteed to be stripped of control characters (< 0x20).
94
95	Note that this has the same requirement as POSITION, that the title needs to
96	be stored for newly created windows until a STATE is sent. It is however not
97	guaranteed that a TITLE will be sent before the first STATE.
98
99
100	ZCHANGE
101	-------
102
103	The window moved in z order.
104
105	Syntax:
106	ZCHANGE,<ID>,<BEHIND>,<FLAGS>
107
108	The window with the id ID is behind the window with the id BEHIND. If
109	BEHIND is 0, then this window should be brought to the front.
110
111	STATE
112	-----
113
114	Changes the window's state and/or title.
115
116	Syntax:
117	STATE,<ID>,<STATE>,<FLAGS>
118
119	State can have one of three values:
120	0 : "Normal" window.
121	1 : Minimized.
122	2 : Maximized.
123
124	The initial STATE for a window will always be preceeded by one CREATE and one
125	POSITION. Optionally, a TITLE may also be sent before the first STATE.
126
127	DEBUG
128	-----
129
130	Debug output from the server component.
131
132	Syntax:
133	DEBUG,<STRING>
134
135	Used for debugging.
136
137	SYNCBEGIN
138	---------
139
140	Indicates that a synchronisation has begun.
141
142	Syntax:
143	SYNCBEGIN,<FLAGS>
144
145	Sent when the server starts a synchronisation. The client should flush all
146	information at this point.
147
148	SYNCEND
149	-------
150
151	Indicates that a synchronisation is complete.
152
153	Syntac:
154	SYNCEND,<FLAGS>
155
156	Sent when the last message that is part of the synchronisation has been sent.
157	This may be followed by duplicate messages and/or messages referring invalid
158	windows that were queued up during the synchronisation.
159
160	Client to Server Operations
161	===========================
162
163	SYNC
164	----
165
166	Request a synchronisation of window information.
167
168	Syntax:
169	SYNC,<FLAGS>
170
171	For each window, the server will send CREATE, POSITION and STATE, in that
172	order, just as if the window was created. Note that a TITLE may also,
173	optionally, be sent before the STATE.
174
175	POSITION
176	--------
177
178	Identical to the command sent from server to client.
179
180	TITLE
181	-----
182
183	Identical to the command sent from server to client.
184
185	ZCHANGE
186	-------
187
188	Identical to the command sent from server to client.
189
190	STATE
191	-----
192
193	Identical to the command sent from server to client.
194
195	FOCUS
196	-----
197
198	Sets which window has input focus.
199
200	Syntax:
201	FOCUS,<ID>,<FLAGS>
202
203	Changes which window that will recieve the keyboard events. Note that this
204	might cause the window to change z order.