--------------------------------------------------------------------- Command: assign-id Assign new ID to client, or fetch current ID Purpose: assigning ID to clients so server can respond to that client Compulsivity: manditory (core infrastructure) More documentation: doc/messages Reference implementation: mds-server --------------------------------------------------------------------- Command: intercept Sign up for reception of message Optional header: Stop Stop reception of messages if `yes` Optional header: Priority Signed 64-bit integer of reception priority (reversed of order) Optional header: Modifying Send message asynchronously and await modification if `yes` Optional header: Length Length of the message Message: list of headers and header–value-pairs that qualifies a message for reception, all messages qualifies if this list is empty Purpose: filter received message for clients and servers Purpose: assigned interception order for modification of messages Compulsivity: manditory (core infrastructure) More documentation: doc/messages Reference implementation: mds-server --------------------------------------------------------------------- Command: echo Echo back a message Required header: Client ID Your ID, provided by `ID assignment` in response to `Command: assign-id` Optional header: Length Length of the message Message: message to echo Purpose: debugging and testing Purpose: network heartbeat Compulsivity: recommended for network enabled servers Reference implementation: mds-echo --------------------------------------------------------------------- Command: register Register availability of a command for which you implement a service Required header: Client ID Your ID, provided by `ID assignment` in response to `Command: assign-id` Conditionally required header: Length Required if: `Action: list` Length of the message Optional header: Action Remove availability for registry if `remove`. Wait until listed commands are available if `wait`, however if a protocol becomes unavailable during this wait period it will still be counted as available for this wait action. Send a list of availability commands if `list`. Conditionally optional header: Time to live Available and optional if: `Action: wait` The maximum number of seconds to wait. Message: List of values for the header `Command` that you implement Purpose: Identify supported display server operations Purpose: Initialisation process synchronisation Compulsivity: highly recommended (infrastructure), programs may stall a bit from time to time without it, or at initialisation depending on the program's implementation Reference implementation: mds-registry --------------------------------------------------------------------- Command: reregister Request that all servers resends `Command: register` with either `Action: add` or without the `Action` header (does the same thing) Purpose: Rebuild registry created with `Command: register` if the registry server crashes Compulsivity: highly recommended (infrastructure), programs may think a protocol is not supported of the registry server crashes if you do not implement this in your server --------------------------------------------------------------------- Command: clipboard Read or manipulate a clipboard Required header: Level The clipboard level, an [1, 3] integer: 1 "primary". Text copied/pasted using the keyboard or a menu item 2 "secondary". Text copied/pasted using the rat 3 "tertiary". Non-text, it is customary for this data to begin with a line describing the data type. Required header: Action What to do with the clipboard: add) Write the message to the clipboard read) Read the clipboard clear) Clear all entries on the selected level on the clipboard set-size) Shrink/grow the clipstack get-size) Read the size of the clipstack In the reply, the server will send: Size: Used: Conditionally required header: Length Required if: `Action: add` Length of the message Conditionally required header: Size Required if: `Action: set-size` The maximum number of elements in the clipstack Conditionally required header: Client ID Your ID, provided by `ID assignment` in response to `Command: assign-id`. Required if: `Action: add` and a header starting with `Time to live: until-death` Required if: `Action: read` Required if: `Action: get-size` Conditionally optional header: Index Available and optional if: `Action: read` The index of the item in the clipstack, starting at 0 Conditionally optional header: Time to live Available and optional if: `Action: add` The number of seconds the entry should be available before it is removed by the server, or: until-death: remove entry when the client closes until-death #: remove entry when the client closes, or # seconds have elapsed forever: never remove it (default) The server will always remove the entry when: 1) it is at the bottom of the clipstack and a new entry is added to the clipstack 2) `Action: clear` is issued for the clipstack The entry will also be removed, unless `Time to live: forever`, if the server crashes or is reexecuted. It is up to the implementation to choose when the removal actually takes place. For example, the reference implementation will pop entries that have timed out when a new entry is added, the reading on the clipstack is requested or the server is reexecuted, but another implement may choose to pop entires asynchronously using another thread or an alarm an pop when when SIGARLM is received. Message: The content to add to the clipboard Purpose: Enable the user to duplicate content from one process into another process without requiring those processes to be aware of eathother to any extent Compulsivity: optional Reference implementation: mds-clipboard --------------------------------------------------------------------- Command: clipboard-info The clipboard server sends out some information about what it is doing, such as automatically removing entires Included header: Event pop) An item in the clipstack has been removed Included headers: Level: The clipboard level that has been affected Popped: The index of the item in the clipstack that has been removed Size: Configured maximum size of the clipstack Used: Number of elements currently in the clipstack crash) The clipboard has been reset because of a software crash Purpose: Enable clients to get notification about changes to the clipboard, that cannot trivially derived from `Command: clipboard` Compulsivity: optional, optional add-on to the clipboard's functionallity Reference implementation: mds-clipboard --------------------------------------------------------------------- Command: add-tray-icon Add a status icons to the status icon tray The client should keep in mind that there can be any number of trays available on the system: zero, one, two or three, ..., and that it will get a response once from every tray Required header: Client ID Your ID, provided by `ID assignment` in response to `Command: assign-id` Required header: Package The name of the package to which the program announced the icon belongs Required header: Icon ID An ID of the icon that can be used identify the icon, icon ID:s are not unique, but the combination of a package and a icon ID should be unque and can be used to ignore already added icons and hide icons that the user has been configured to be hidden Required header: Title A title describing the icon for the user, used to configured when icons should be hidden and shown among other configuration Required header: Icon The name or pathname of an icon to use together with the title Response: To: In response to: Message ID: Socket: Will send update: <`yes` if this message will be followed by `Command: tray-update`, otherwise `no`> Purpose: Enable clients to add a small icon that displays the status of programs, particularly minimised programs and services Compulsivity: optional --------------------------------------------------------------------- Command: update-tray-icon Change the status of a status icon Required header: Status hide) Hide the icon show) Show the icon active) The icon is active inactive) The icon is inactive Purpose: Enable status trays to automatically hide inactive icons Purpose: Hide icons without actually removing them Compulsivity: required if supporting `Command: add-tray-icon`, only `Status: hide` and `Status show` is required --------------------------------------------------------------------- Command: tray-update Send updates about the status tray to the status icon Required header: Socket Where the icon is embedded, used to identify the affected tray Conditionally required header: Max colour Required if: `Colour`-header is used Required if: `Foreground`-header is used Required if: `Alpha`-header is used The maximum colour component value, for example, if using 24-bit colour, which component will be 8-bit and the maximum value will be 255, this also applies to the alpha component Conditionally required header: Size Required if, otherwise optional: `Length`-header is used The width and height, in pixels, the icon should have Conditionally required header: Has alpha Required if: `Length`-header is used yes) The message contains an alpha channel no) The message does not contain an alpha channel Conditionally required header: Bytes Required if: `Length`-header is used The number of bytes the subpixels used, for example, 24-bit colours will have this set to 1 because each subpixel has 8 bits, 48-bit colours will have this set to 2 because each subpixel has 16 bits Allowed values are: 1, 2, 4 and 8. These values are used used so that CPU:s with any endianness can be trivially used as the words sizes are guaranteed to be supported in C, and mixed/middle-endiannes gets complicated if we go outside this. Conditionally optional/required header: Colour Available and optional if: `Length`-header is not used Required if: `Foreground`-header but not `Length`-header is used Single blank space-separated [0, ] sRGB 3-tuple Conditionally optional header: Foreground Single blank space-separated [0, ] sRGB 3-tuple Optional header: Alpha The opacity of the tray Optional header: Length Length of the message Optional header: Use urgency yes) The icon tray may blink no) The icon tray may not blink Message: Raw binary encoding of the background image, bytes are orders: row, pixel, channel (alpha, red, green, blue), subpixel value (native CPU encoding). The Alpha channel should be included but ignored if `Has alpha: no`, in such as it is best to set it to full. Example image (with `Bytes: 2`, `Has alpha: no` and `Size: 3`): sRGB(x0102, 0, 0), sRGB(0, x0304, 0), sRGB(0, 0, x0506) sRGB(x0708, 0, 0), sRGB(0, x090A, 0), sRGB(0, 0, x0B0C) sRGB(x0D0E, 0, 0), sRGB(0, x0F10, 0), sRGB(0, 0, x1112) Encoding of example image (hexadecimal): FFFF 0102 0000 0000 FFFF 0000 0304 0000 FFFF 0000 0000 0506 FFFF 0708 0000 0000 FFFF 0000 090A 0000 FFFF 0000 0000 0B0C FFFF 0D0E 0000 0000 FFFF 0000 0F10 0000 FFFF 0000 0000 1112 Note that on a big-endian system this would be: FF FF 02 01 00 00 00 00 FF FF 00 00 04 03 00 00 FF FF 00 00 00 00 06 05 FF FF 08 07 00 00 00 00 FF FF 00 00 0A 09 00 00 FF FF 00 00 00 00 0C 0B FF FF 0E 0D 00 00 00 00 FF FF 00 00 10 0F 00 00 FF FF 00 00 00 00 12 11 (x86_64 computers are big-endian) It is up to the networking servers to translate the encoding between machines. (The host translates to big-endian unless they can confirm that they have the same endianness.) Purpose: Enable clients to be aware of the appearance of the tray, such as colours, transparency and background image Purpose: Enable clients to be aware of how the user wants status icons to behave Compulsivity: optional --------------------------------------------------------------------- Command: new-tray Announce the existence of a new status icon trays Purpose: Allow clients to add their status icons to status icon trays that have been added to the display after those programs have started and attempted to add their icons Compulsivity: required if supporting `Command: add-tray-icon` --------------------------------------------------------------------- Command: key-sent Announce a keyboard input event Required header: Keyboard Any string that uniquely identifies the keyboard Purpose: Enable multi-keyboard aware programs and give at least on keyboard per seat in a multi-seat environment Note: mds-kkbd uses `kernel` to indicate that it uses the kernel and thus lumps together all keyboards. Required header: Released `yes` if the key was released `no` otherwise, that is, held down or pressed Note: pause/break is automatically released directly after it has been pressed. This is feature built into keyboards and servers should not try to circumvent this Required header: Keycode An unsigned 14-bit integer identifying the key, may be remapped Optional header: Scancode Either an unsigned 7-bit integer or a single blank space separated trio of unsigned 7-bit integers, identifying the key. This is the scancode sent from the keyboard and optionally unified by the keyboard driver, however with the typed/released bit zeroed out. This may not be remapped. Optional header: Modifiers Single blank space separated list of active modifiers: shift) Shift (level 2) ctrl) Control alt) Alternative/Option altgr) Alternative Graphic (level 3) lvl*) * may be any 2ⁿ + 1 integer with 1 < n < 20 super) Super hyper) Hyper ultra) Ultra caps) Caps (usually a lock key) num) Num (usually a lock key) scrl) Scroll (usually a lock key) top) Top (historical) front) Front (historical) greek) Greek (historical) compose) Compose (rare, it is usally a dead key) Any key that has been locked should be prefix with `+`, if the key has been locked by nullified with non-lock modifier it should be prefixed with a `-`. If no modifier is active or has been nullified, `none` should be used. Optional header: Key A textual representation of the key that has been typed or released, as mapped by the keyboard layout. esc) Escape f*) F* where * is any integer sysrq) System Request/Print Screen scrl) Scroll (lock) break) Break/Pause backspace) Backspace tab) Tab return) Return/Enter space) Blank Space menu) Application Menu ins) Insert home) Home pgup) Page Up del) Delete end) End pgdown) Page Down up) Up Arrow left) Left Arrow down) Down Arrow right) Right Arrow shift) Shift (level 2) begin) Begin (keypad 5 in nagivation mode) ctrl) Control alt) Alternative/Option altgr) Alternative Graphic (level 3) lvl*) * may be any 2ⁿ + 1 integer with 1 < n < 20 super) Super hyper) Hyper ultra) Ultra caps) Caps (usually a lock key) num) Num (usually a lock key) scrl) Scroll (usually a lock key) top) Top (historical) front) Front (historical) greek) Greek (historical) compose) Compose (usally a dead key) hexcompose) Hex-Compose (usally a dead key) (use to create aribitrary characters) longhexcompose) Long Hex-Compose (usally a dead key) (variant of hexcompose for longer codepoints) modelock) Mode Lock letter *) * may be any UTF-8 encoded letter Keys that lock/unlock a modifer should be suffixed with a blank space and a `lock`. If the key is a dead key (even the compose key) should use `dead` instead. A position, either `left`, `right`, `keypad` or an index, followed by a blank space, should prefix any key that occurs on multiple position on the keyboard, unless it only appears on the keypad once and once not on the keypad. Keys without any meaning should be identified as `unknown`. Modifiers and dead keys should not affect the value. Optional header: Characters UTF-8 encoded string that has been written Purpose: Enable the user to use a keyboard, physical or on-screen Purpose: Enable programs to send keys as part of a script or a reply of a recorded session Compulsivity: highly-recommended, a computer is as good as useless without a keyboard Reference implementation: kkbd Reference implementation: kbd Reference implementation: keytrans --------------------------------------------------------------------- Command: enumerate-keyboards List available keyboards Required header: Client ID Your ID, provided by `ID assignment` in response to `Command: assign-id` Instructions: This message must be consumed by the first server that receives it and implements support for it, and then send out a `Command: keyboard-enumeration` populated with the keyboard it provide as named in the `Keyboard` header for protocols such as `Command: key-sent` Purpose: Make it possible for clients to list all available keyboards so that can be configured individually Compulsivity: optional Reference implementation: kkbd Reference implementation: kbd --------------------------------------------------------------------- Command: keyboard-enumeration Response to `enumerate-keyboards` Required header: To The ID received under `Client ID` in the `Command: enumerate-keyboards` message that triggered this message to be broadcasted Required header: In response to The ID received under `Message ID` in the `Command: enumerate-keyboards` message that triggered this message to be broadcasted Required header: Length Length of the message Message: New line separated list of available keyboards Instructions: All keyboard servers should listen for this message and append all keyboards it implement to the message once recieved Purpose: Make it possible for clients to list all available keyboards so that can be configured individually Compulsivity: required if you implement `Command: enumerate-keyboards` Reference implementation: kkbd Reference implementation: kbd --------------------------------------------------------------------- Command: set-keyboard-leds Activate and deactivate LED:s on a keyboard Required header: Active LED:s that should be turned on. If a LED is listed here but not in `Mask` that LED should be turned on if it is off, and turned off if it is on. The value is a single blank space separated list of LED:s: num) Num lock caps) Caps lock scroll) Scroll lock compose) Compose Unsupported LED:s should be silently ignored. Required header: Mask LED:s listed here that do not appear in `Active` should be turned off. The value of this header follows the same rules as for `Active`. Optional header: Keyboard A string that identifies the keyboard that should be affected. If omitted all keyboard are affected. Purpose: Enable keyboard layout servers to activate and deactive LED:s on the keyboard to indicate active locks Compulsivity: optional Reference implementation: kkbd Reference implementation: kbd Reference implementation: kbdtrans --------------------------------------------------------------------- Command: get-keyboard-leds List exisiting LED:s on a keyboard and their state Required header: Client ID Your ID, provided by `ID assignment` in response to `Command: assign-id` Required header: Keyboard A string that identifies the keyboard that should be affected Response: The server implementing support for `Command: get-keyboard-leds` for the keyboard indicated by `Keyboard` should send a message back to the client indicated by `Client ID` (using the `To` header) with the headers: Active: list of currently turned on LED:s Present: list of LED:s that the server believes to be present on the keyboards Both of these headers followes the rules of the `Active` header under `Command: set-keyboard-leds` Purpose: Enable keyboard layout servers to automatically set active locks when the server starts based on currently active LED:s Compulsivity: recommended, required if you implement support for `Command: set-keyboard-leds`. If you do not support this protocol servers and clients and stall when they try to get the active LED:s Reference implementation: kkbd Reference implementation: kbd Reference implementation: kbdtrans --------------------------------------------------------------------- Command: keycode-map Remap keyboard keycodes and query current mapping Required header: Action remap) Remap keys reset) Reset all mappings to identity mapping query) Query mapping Each affected server will send a message format like that of `Action: remap` with current mapping that are not identity mappings Optional header: Keyboard A string that identifies the keyboard that should be affected. If omitted all keyboard are affected. Conditionally required header: Client ID Required if: `Action: query` Your ID, provided by `ID assignment` in response to `Command: assign-id` Conditionally optional header: Length Available and optional if: `Action: remap` The length of the message Message: Each line contains contains two single space delimited numbers, the first number is the keycode as determined by the scancode, the second number is keycode that scancode should generate. For example, `1 1` resets Escape to be mapped to Escape, and `1 59` remaps Escape to F1, while `1 59\n59 1`, where `\n` is a new lone, swaps Escape and F1. Purpose: Enable the user to swap or replace keys on the keyboard Purpose: Enable the user manually correct an incorrectly mapped keyboard Compulsivity: optional Reference implementation: kkbd Reference implementation: kbd --------------------------------------------------------------------- Command: new-keyboard Announce the existance of a new keyboard Required header: Length The length of the message Message: List of strings that identifies the keyboards that have been added. Purpose: Enable servers and clients to detect new keyboards Compulsivity: recommended Reference implementation: kkbd Reference implementation: kbd --------------------------------------------------------------------- Command: old-keyboard Announce the removal of an old keyboard Required header: Length The length of the message Message: List of strings that identifies the keyboards that have been removed. Purpose: Enable servers and clients to detect removal of keyboards Compulsivity: recommended Reference implementation: kbd --------------------------------------------------------------------- Command: error Notify a client about a request failure Required header: To The ID of the client that send a request that failed Required header: In response to The ID of the message whose request failed Required header: Error The errno number of the error, 0 on success if the message was not an information query. The string "custom" can be used if there is not errno number, optionally followed by a blank space and a number that identifies the error, this number must be positive (not zero). Conditionally optional header: Length Available and optional if: "custom" as used in `Error` The length of the message Message: Description of the error, single line, mid-sentence case, no punctuation in the end, must not be question but rather it must be a statement Purpose: Enable keyboard layout servers to automatically set active locks when the server starts based on currently active LED:s Compulsivity: optional --------------------------------------------------------------------- Command: get-vt Get the index of the virtual terminal the server is display on and the servers file descriptor for that tty Required header: Client ID Your ID, provided by `ID assignment` in response to `Command: assign-id` Response: The server will response with the header `VT index` and the index of the virtual terminal the server is display on in decimal format. Additionally the server will respond with the header `Active` with the value `yes` if the VT is in the foreground or the value `no` if the VT is in the background. Purpose: Allow programs to be aware of whether the display is in the foreground or the background Purpose: Allow programs to be aware of which VT the server is running on Purpose: Allow programs to gain access of the TTY associated with the VT such that they can use ioctl and similar calls on that TTY Compulsivity: required Reference implementation: vt --------------------------------------------------------------------- Command: configure-vt Reconfigure the virtual terminal the server is display on Required header: Client ID Your ID, provided by `ID assignment` in response to `Command: assign-id` Optional header: graphical yes) Set the TTY graphical mode no) Set the TTY text mode The server implementing this protocol should not set the TTY to text mode temporarily when switching TTY. It is up the the server that set the request for graphical mode to temporarily switch to text mode when switching TTY. Optional header: exclusive yes) The server may block other process from opening the TTY. no) The server may not block other process from opening the TTY. Response: The server will response with a `Command: error` Purpose: Allow presentation servers to enter and leave graphical mode Purpose: Allow programs to gain access of the TTY associated with the VT such that they can use ioctl and similar calls on that TTY Compulsivity: required Reference implementation: vt --------------------------------------------------------------------- Command: switching-vt Notify servers about an ongoing virtual terminal switch Required header: Status deactivating) The kernel wants to place the display in the background activating) The kernel wants to place the display in the foreground Instructions: When a virtual terminal switch is requested the server implementing control VT switching involving the display's virtual terminal will get signaled by the kernel. Upon this signal the server should roadcast this command. All servers that need to release or acquire resouces should intercept this message with the possibility of modifying it. Once a server is ready for the VT to switch it should let the message pass to the next server by telling the master server that it is no modification to do. Once all servers are read for the switch the server that emitted this message should signal the kernel that it may switch VT. The server should detect this by setting up secondary contection to the display that intercepts this message. This connection should intercept this message with priority −2⁶³, all servers that need to perform actions before the switch takes place must have a priority higher than −2⁶³, preferably 0. Purpose: Allow servers to release resources when the user switch virtual terminal before the terminal actually changes and to reacquire resources when the virtual terminal become active again Compulsivity: required Reference implementation: vt Reference implementation: kkbd ---------------------------------------------------------------------