Version 29 (modified by 8 years ago) (diff) | ,
---|
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
andencodings.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.