Network Protocol

Introduction

This page documents the types of messages that the client and server can exchange. It may not always be up to date, the best reference remains the actual code.

See also:

• wiki/PacketEncoding for the encoding and compression of these messages
• wiki/Network for the actual network connection

Overview

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 or server which does not implement all the features should disable the capability rather than ignoring the corresponding packets.

By default, the packet type is normally a string, as shown in the tables below. As of v0.9.0 the clients and server can also exchange a list of aliases in the hello packet so that each string can be replaced with a smaller identifier instead. This can be disabled for debugging the network packet layer by setting the environment variable XPRA_USE_ALIASES to any value other than 1.

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		sent by the network layer when the network connection has dropped	free any resources
gibberish		sent by the network layer when the network received unparseable data, data decompression failed or decryption failed	disconnect the connection and free any resources
set_deflate	new compression level	request a change in the connection's compression level	the server should honour it and echo the same packet back to the client

---

• Packets sent by the server

Packet Type	Arguments	Purpose	Actions Required	Client Capability Required
startup-complete		notifies the client that all the windows have been sent		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
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
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 must move and resize the window
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
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
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
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)
info-response	dictionary with details	response to an info-request sent by the client	the client may use the details, ie: present them to the user

---

• 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
map-window	window ID, position and properties	tells the server where the window has been mapped on the client	the server must ensure its window is at the same location
unmap-window	window ID	the window is no longer shown	the server should do the same and park the window
configure-window	window ID, position, size and properties	the client has modified the window in some way	the server must ensure its window matches
close-window	window ID	the client has requested that the window be closed	the server should ask the application to close the window, it may force it to do so
focus	window ID and keyboard state	the client has focused a different window, or none at all	the server should ensure its focus state matches
button-action	window ID, button, pressed or unpressed, position and keyboard modifiers state	the client has clicked on a window (or used the mouse wheel)	the server should try to simulate pressing or unpressing the same button
pointer-position	window ID, position and keyboard modifiers state	the user is moving its mouse over a window	the server should try to move its mouse to the same position
key-action	key definition (keycode, key name, pressed or unpressed, etc)	the user has pressed a key	the server should try to simulate pressing the same key
key-repeat	key definition (as above)	the key is still pressed	the server may use this information to continue pressing the same key, cancelling any timeouts it may have - this is only relevant when the keyboard state is synchronized
layout-changed	layout and variant	the client keyboard configuration has changed	the server should try to update its keyboard configuration to match
keymap-changed	a dictionary of keyboard definitions	the client keyboard configuration has changed	the server should try to update its keyboard configuration to match
damage-sequence	sequence ID and decoding details	the client is acknowledging that it has painted a screen update received in a draw packet	the server may use this information to estimate the performance of the connection and of the client, and may decide to send more screen updates
server-settings	settings	the client's xsettings have changed	the server should apply the new settings
jpeg-quality (deprecated) or quality	new fixed picture quality value from -1 to 100	the client wants to use a fixed quality (0 to 100), or disable fixed quality (-1)	the server should honour the request, it may refresh all the windows with the new setting	change-quality
min-quality	new minimum picture quality value			change-min-quality
speed	new fixed speed value from -1 to 100	the client wants to use a fixed speed (0 to 100), or disable fixed speed (-1)	the server should honour the request, it may refresh all the windows with the new setting	change-speed
min-speed	new minimum speed setting			change-min-speed
info-request	client UUID and list of window IDs	request the server to send detailed statistics including those for the windows given	the server should send an info-response packet back with the information	info-request
suspend	UI flag, list of window IDs	tell the server to stop sending window updates, and if the UI flag is set, also stop clipboard, sound, etc	the server should honour this request	suspend-resume
resume	UI flag, list of window IDs	tell the server to resume window updates suspended with suspend	the server should honour the request and should refresh all the windows	suspend-resume
encoding	new encoding, window IDs	tell the server to switch to a different encoding for the given windows	the server should honour the request and should refresh all the windows with the new encoding
buffer-refresh	window ID (or -1 for all), unused value, quality and if the server supports window_refresh_config: refresh options and client properties	the client should refresh the window(s) specified and update its batching and client properties as specified
desktop_size	width, height, screen(s) specification	the client's can tell the server that its screen resolution has changed	the server should ensure that its virtual screen is big enough to accommodate the new size, it should tell the client about the resolution it settled on using a desktop_size packet of its own, it may update other attributes ("workarea", etc)
rpc	rpc_type and type specific arguments (only dbus supported at present)	the client is requesting the server to perform a dbus call	the server should call the dbus function specified and reply with a rpc-reply packet	dbus_proxy
sound-control	command and optional arguments	the client may use this call to stop, start, fadein, fadeout or request a new-sequence	the server should honour it
shutdown-server		the client (usually a command line client like xpra stop) wants to stop the server	the server should disconnect all the clients and shutdown cleanly, stopping the display if it owns it
exit-server		the client (usually a command line client like xpra exit wants the server to exit	the server should disconnect all the clients and exit, unlike shutdown it should not stop the display
disconnect		the client wants to be disconnected cleanly	the server should close the client connection cleanly	exit_server
screenshot		the client wants a screenshot of all the active windows	the server should reply with a screenshot packet containing the screenshot as a PNG image

---

Notes:

• Changing speed or quality is not applicable to all encodings, the server will expose the relevant encodings through the capabilities: encodings.with_speed, encodings.with_quality and encodings.with_lossless_mode (for quality=100%)
• Changing xsettings, clipboard or bell settings may not be possible if those features are disabled by the server - in which case the server will simply ignore the request
• The packets changing settings usually affect only the current client connection. To affect other connections (if there are more than one), use the "xpra control" interface.