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

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	many	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	many	tells the client about a new tray window	the client should show the new system tray	system_tray
raise-window	window ID	the window should be raised	the client may or may not honour the request to raise the window	window.raise
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
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