path: root/doc/protocols

---------------------------------------------------------------------

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: <configured maximum size of the clipstack>
	Used: <number of elements currently in the clipstack>

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: <Client ID>
  In response to: <Message ID>
  Message ID: <the status tray's message ID>
  Socket: <Where to embed the icon>
  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, <Max colour>] sRGB 3-tuple

Conditionally optional header: Foreground
  Single blank space-separated [0, <Max colour>] 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

---------------------------------------------------------------------