xpra icon
Bug tracker and wiki

Network Protocol


Warnings:

  • very detailed technical details of little interest to most common mortals
  • already out of date


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:

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
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-lost sent by the network layer when the network connection has droppedfree any resources
gibberish sent by the network layer when the network received unparseable data, data decompression failed or decryption faileddisconnect the connection and free any resources
set_deflatenew compression levelrequest a change in the connection's compression levelthe 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 attributestells 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 window
new-traywindow ID and attributestells 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 used
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 must move and resize the window
window-move-resizewindow ID, new position and sizehonour applications that request the window to be moved and resizedthe client should move and resize the windowserver-window-move-resize
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 window
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 dimensions
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 data
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)
info-responsedictionary with detailsresponse to an info-request sent by the clientthe 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-enablednew stateenable or disable clipboard synchronizationthe server should honour the requestclipboard
set-keyboard-sync-enablednew stateenable or disable keyboard synchronizationthe server should honour the requesttoggle_keyboard_sync
set-cursorsnew stateenable or disable sending of cursor datathe server should honour the requesttoggle_cursors_bell_notify
set-notifynew stateenable or disable sending of notificationsthe server should honour the requesttoggle_cursors_bell_notify
set-bellnew stateenable or disable sending of bell eventsthe server should honour the requesttoggle_cursors_bell_notify
map-windowwindow ID, position and propertiestells the server where the window has been mapped on the clientthe server must ensure its window is at the same location
unmap-windowwindow IDthe window is no longer shownthe server should do the same and park the window
configure-windowwindow ID, position, size and propertiesthe client has modified the window in some waythe server must ensure its window matches
close-windowwindow IDthe client has requested that the window be closedthe server should ask the application to close the window, it may force it to do so
focuswindow ID and keyboard statethe client has focused a different window, or none at allthe server should ensure its focus state matches
button-actionwindow ID, button, pressed or unpressed, position and keyboard modifiers statethe client has clicked on a window (or used the mouse wheel)the server should try to simulate pressing or unpressing the same button
pointer-positionwindow ID, position and keyboard modifiers statethe user is moving its mouse over a windowthe server should try to move its mouse to the same position
key-actionkey definition (keycode, key name, pressed or unpressed, etc)the user has pressed a keythe server should try to simulate pressing the same key
key-repeatkey definition (as above)the key is still pressedthe 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-changedlayout and variantthe client keyboard configuration has changedthe server should try to update its keyboard configuration to match
keymap-changeda dictionary of keyboard definitionsthe client keyboard configuration has changedthe server should try to update its keyboard configuration to match
damage-sequencesequence ID and decoding detailsthe client is acknowledging that it has painted a screen update received in a draw packetthe 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-settingssettingsthe client's xsettings have changedthe server should apply the new settings
jpeg-quality (deprecated) or
quality
new fixed picture quality value from -1 to 100the 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 settingchange-quality
min-qualitynew minimum picture quality value change-min-quality
speednew fixed speed value from -1 to 100the 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 settingchange-speed
min-speednew minimum speed setting change-min-speed
info-requestclient UUID and list of window IDsrequest the server to send detailed statistics including those for the windows giventhe server should send an info-response packet back with the informationinfo-request
suspendUI flag, list of window IDstell the server to stop sending window updates, and if the UI flag is set, also stop clipboard, sound, etcthe server should honour this requestsuspend-resume
resumeUI flag, list of window IDstell the server to resume window updates suspended with suspendthe server should honour the request and should refresh all the windowssuspend-resume
encodingnew encoding, window IDstell the server to switch to a different encoding for the given windowsthe server should honour the request and should refresh all the windows with the new encoding
buffer-refreshwindow ID (or -1 for all), unused value, quality and if the server supports window_refresh_config: refresh options and client propertiesthe client should refresh the window(s) specified and update its batching and client properties as specified
desktop_sizewidth, height, screen(s) specificationthe client's can tell the server that its screen resolution has changedthe 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)
rpcrpc_type and type specific arguments (only dbus supported at present)the client is requesting the server to perform a dbus callthe server should call the dbus function specified and reply with a rpc-reply packetdbus_proxy
sound-controlcommand and optional argumentsthe client may use this call to stop, start, fadein, fadeout or request a new-sequencethe server should honour it
shutdown-server the client (usually a command line client like xpra stop) wants to stop the serverthe 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 exitthe server should disconnect all the clients and exit, unlike shutdown it should not stop the display
disconnect the client wants to be disconnected cleanlythe server should close the client connection cleanlyexit_server
screenshot the client wants a screenshot of all the active windowsthe 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.
Last modified 6 months ago Last modified on 09/13/16 12:58:05