Network Protocol

Introduction

This page documents the types of messages that the client and server can exchange. For the actual network connection see wiki/Network and for the encoding and compression of the messages see wiki/PacketEncoding.
The most important packet is the first one sent, the hello packet, since it contains "capabilities" which determines what packets and features are supported by the other end. In a lot of cases, a client which does not implement all the features should disable the capability rather than ignoring the corresponding packets.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in ​RFC 2119.

• General packets that flow in both directions:

Packet Type	Arguments	Purpose	Actions Required
hello	a dictionary containing connection options and capabilities	authentication (if required), setup of keyboard, configuration options, etc	the receiver must either accept the connection and send a hello back as acknowledgement, send a challenge request or disconnect
ping	time to be echoed back	monitor connection state, collect latency statistics	The receiver must send a ping-echo back
ping-echo	echoed time, load average, measured latency	response to ping	none, it should be used to collect latency statistics
sound-data	sound buffers and associated metadata	forward sound data	the receiver should queue the sound buffer, it may drop them if desired - if so, it should tell the other end to stop sending
connection-lost	none	sent by the network layer when the network connection has dropped	free any resources
gibberish	none	sent by the network layer when the network received unparseable data, data decompression failed or decryption failed	disconnect the connection and free any resources

• Packets sent by the server

must move and resize the window

Packet Type	Arguments	Purpose	Actions Required	Client Capability Required
startup-complete	none	notifies the client that all the windows have been sent	none	notify-startup-complete
new-window and new-override-redirect	window ID and attributes	tells the client about a new regular window or override-redirect window	the client should show the new window, it should eventually send a map-window packet with the location of the window	none
new-tray	window ID and attributes	tells the client about a new tray window	the client should show the new system tray	system_tray
lost-window	window ID	the application has closed the given window	the client must close the given window or tray, which can not longer be used	none
raise-window	window ID	the application has requested that the window be raised	the client should raise the window	window.raise
configure-override-redirect	window ID, new position and size	honour applications that reconfigure their override redirect windows	the client
none
window-move-resize	window ID, new position and size	honour applications that request the window to be moved and resized	the client should move and resize the window	server-window-move-resize
window-resized	window ID and new size	honour applications that request the window to be resized - this is only a deprecated fallback for window-move-resize	the client should move and resize the window	server-window-resize
window-icon	window ID and icon data	new icon for the given window	the client may display this new icon in the window's title bar, etc	raw_window_icons
window-metadata	window ID and metadata dictionary	update the metadata associated with a window	the client should apply the new attributes to the given window	none
cursor	the cursor data (see code for details)	honour applications that request a different cursor	the client should display the new cursor immediately	cursors
bell	the bell sound definition (see code for details)	honour applications requesting the bell to ring	the client should ring the "bell" or its equivallent	bell
notify_show	notification ID, message, etc	honour applications which request that a notification be shown to the user	the client should show the notification	notifications
notify_close	notification ID	the notification should be closed	the client should stop showing the given notification	notifications
set-clipboard-enabled	new state, reason for change	the server requests that clipboard synchronization be turned on or off	the client should honour the request	clipboard.set_enabled
desktop_size	dimensions	the server has resized the virtual display	the client may record and use these new dimensions	none
draw	position of the update within the window and the pixel data	an area of the window must be re-painted	the client must repaint the window with the new pixel data	none
rpc-reply	rpc response	the server is responding to a rpc packet	the client should be able to match the response to a query it sent (only dbus rpc is supported at present)	dbus_proxy
control	control command and arguments	the server is requesting a configuration change	the client may honour it	control_commands (list)

• Packets sent by the client

Packet Type	Arguments	Purpose	Actions Required	Server Capability Required
set-clipboard-enabled	new state	enable or disable clipboard synchronization	the server should honour the request	clipboard
set-keyboard-sync-enabled	new state	enable or disable keyboard synchronization	the server should honour the request	toggle_keyboard_sync
set-cursors	new state	enable or disable sending of cursor data	the server should honour the request	toggle_cursors_bell_notify
set-notify	new state	enable or disable sending of notifications	the server should honour the request	toggle_cursors_bell_notify
set-bell	new state	enable or disable sending of bell events	the server should honour the request	toggle_cursors_bell_notify