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

Purpose: Enable status trays to automatically hide inactive icons
Purpose: Hide icons without actually removing them

Compulsivity: optional

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

Command: tray-update
  Send updates about the status tray to the status icon

Purpose: Enable clients to be aware of the appearance of the tray,
	 such as colours, transparency and background image

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`

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