xpra icon
Bug tracker and wiki

Version 11 (modified by Antoine Martin, 6 years ago) (diff)


Network Protocol


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
helloa dictionary containing connection options and capabilitiesauthentication (if required), setup of keyboard, configuration options, etcthe receiver must either accept the connection and send a hello back as acknowledgement, send a challenge request or disconnect
pingtime to be echoed backmonitor connection state, collect latency statisticsThe receiver must send a ping-echo back
ping-echoechoed time, load average, measured latencyresponse to pingnone, it should be used to collect latency statistics
sound-datasound buffers and associated metadataforward sound datathe receiver should queue the sound buffer, it may drop them if desired - if so, it should tell the other end to stop sending
connection-lostnonesent by the network layer when the network connection has droppedfree any resources
gibberishnonesent by the network layer when the network received unparseable data, data decompression failed or decryption faileddisconnect the connection and free any resources
  • Packets sent by the server
must move and resize the windowshould move and resize the window
Packet Type Arguments Purpose Actions Required Client Capability Required
startup-completenonenotifies the client that all the windows have been sentnonenotify-startup-complete
new-window and
manytells the client about a new regular window or override-redirect windowthe client should show the new window, it should eventually send a map-window packet with the location of the windownone
new-traymanytells the client about a new tray windowthe client should show the new system traysystem_tray
lost-windowwindow IDthe application has closed the given windowthe client must close the given window or tray, which can not longer be usednone
raise-windowwindow IDthe application has requested that the window be raisedthe client should raise the windowwindow.raise
configure-override-redirectwindow ID, new position and sizehonour applications that reconfigure their override redirect windowsthe client
window-move-resizewindow ID, new position and sizehonour applications that request the window to be moved and resizedthe client
window-resizedwindow ID and new sizehonour applications that request the window to be resized - this is only a deprecated fallback for window-move-resizethe client should move and resize the windowserver-window-resize
window-iconwindow ID and icon datanew icon for the given windowthe client may display this new icon in the window's title bar, etcraw_window_icons
window-metadatawindow ID and metadata dictionaryupdate the metadata associated with a windowthe client should apply the new attributes to the given windownone
cursorthe cursor data (see code for details)honour applications that request a different cursorthe client should display the new cursor immediatelycursors
bellthe bell sound definition (see code for details)honour applications requesting the bell to ringthe client should ring the "bell" or its equivallentbell
notify_shownotification ID, message, etchonour applications which request that a notification be shown to the userthe client should show the notificationnotifications
notify_closenotification IDthe notification should be closedthe client should stop showing the given notificationnotifications
set-clipboard-enablednew state, reason for changethe server requests that clipboard synchronization be turned on or offthe client should honour the requestclipboard.set_enabled
desktop_sizedimensionsthe server has resized the virtual displaythe client may record and use these new dimensionsnone
drawposition of the update within the window and the pixel dataan area of the window must be re-paintedthe client must repaint the window with the new pixel datanone
rpc-replyrpc responsethe server is responding to a rpc packetthe client should be able to match the response to a query it sent (only dbus rpc is supported at present)dbus_proxy
controlcontrol command and argumentsthe server is requesting a configuration changethe client may honour itcontrol_commands (list)