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

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

CREATE
------

Allocate structures for a new window.

Syntax:
        CREATE,<ID>,<FLAGS>

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


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 : Minimised.
 2 : Maximised.


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 SETSTATE just as
if the window was created.

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