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

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