1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
|
---------------------------------------------------------------------
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
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 (red, green, blue,
then optionally alpha), subpixel value (most
significant byte first)
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):
0102 0000 0000 0000 0304 0000 0000 0000 0506
0708 0000 0000 0000 090A 0000 0000 0000 0B0C
0D0E 0000 0000 0000 0F10 0000 0000 0000 1112
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)
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)
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. 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
---------------------------------------------------------------------
|