docs/interop/barrier.rst

   1 Barrier client protocol
   2 =======================
   3
   4 QEMU's ``input-barrier`` device implements the client end of
   5 the KVM (Keyboard-Video-Mouse) software
   6 `Barrier <https://github.com/debauchee/barrier>`__.
   7
   8 This document briefly describes the protocol as we implement it.
   9
  10 Message format
  11 --------------
  12
  13 Message format between the server and client is in two parts:
  14
  15 #. the payload length, a 32bit integer in network endianness
  16 #. the payload
  17
  18 The payload starts with a 4byte string (without NUL) which is the
  19 command. The first command between the server and the client
  20 is the only command not encoded on 4 bytes ("Barrier").
  21 The remaining part of the payload is decoded according to the command.
  22
  23 Protocol Description
  24 --------------------
  25
  26 This comes from ``barrier/src/lib/barrier/protocol_types.h``.
  27
  28 barrierCmdHello  "Barrier"
  29 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  30
  31 Direction:
  32   server -> client
  33 Parameters:
  34   ``{ int16_t minor, int16_t major }``
  35 Description:
  36   Say hello to client
  37
  38   ``minor`` = protocol major version number supported by server
  39
  40   ``major`` = protocol minor version number supported by server
  41
  42 barrierCmdHelloBack  "Barrier"
  43 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  44
  45 Direction:
  46   client ->server
  47 Parameters:
  48   ``{ int16_t minor, int16_t major, char *name}``
  49 Description:
  50   Respond to hello from server
  51
  52   ``minor`` = protocol major version number supported by client
  53
  54   ``major`` = protocol minor version number supported by client
  55
  56   ``name``  = client name
  57
  58 barrierCmdDInfo  "DINF"
  59 ^^^^^^^^^^^^^^^^^^^^^^^
  60
  61 Direction:
  62   client ->server
  63 Parameters:
  64   ``{ int16_t x_origin, int16_t y_origin, int16_t width, int16_t height, int16_t x, int16_t y}``
  65 Description:
  66   The client screen must send this message in response to the
  67   barrierCmdQInfo message.  It must also send this message when the
  68   screen's resolution changes.  In this case, the client screen should
  69   ignore any barrierCmdDMouseMove messages until it receives a
  70   barrierCmdCInfoAck in order to prevent attempts to move the mouse off
  71   the new screen area.
  72
  73 barrierCmdCNoop  "CNOP"
  74 ^^^^^^^^^^^^^^^^^^^^^^^
  75
  76 Direction:
  77   client -> server
  78 Parameters:
  79   None
  80 Description:
  81   No operation
  82
  83 barrierCmdCClose "CBYE"
  84 ^^^^^^^^^^^^^^^^^^^^^^^
  85
  86 Direction:
  87   server -> client
  88 Parameters:
  89   None
  90 Description:
  91   Close connection
  92
  93 barrierCmdCEnter "CINN"
  94 ^^^^^^^^^^^^^^^^^^^^^^^
  95
  96 Direction:
  97   server -> client
  98 Parameters:
  99   ``{ int16_t x, int16_t y, int32_t seq, int16_t modifier }``
 100 Description:
 101   Enter screen.
 102
 103   ``x``, ``y``  = entering screen absolute coordinates
 104
 105   ``seq``  = sequence number, which is used to order messages between
 106   screens.  the secondary screen must return this number
 107   with some messages
 108
 109   ``modifier`` = modifier key mask.  this will have bits set for each
 110   toggle modifier key that is activated on entry to the
 111   screen.  the secondary screen should adjust its toggle
 112   modifiers to reflect that state.
 113
 114 barrierCmdCLeave "COUT"
 115 ^^^^^^^^^^^^^^^^^^^^^^^
 116
 117 Direction:
 118   server -> client
 119 Parameters:
 120   None
 121 Description:
 122   Leaving screen.  the secondary screen should send clipboard data in
 123   response to this message for those clipboards that it has grabbed
 124   (i.e. has sent a barrierCmdCClipboard for and has not received a
 125   barrierCmdCClipboard for with a greater sequence number) and that
 126   were grabbed or have changed since the last leave.
 127
 128 barrierCmdCClipboard "CCLP"
 129 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 130
 131 Direction:
 132   server -> client
 133 Parameters:
 134   ``{ int8_t id, int32_t seq }``
 135 Description:
 136   Grab clipboard. Sent by screen when some other app on that screen
 137   grabs a clipboard.
 138
 139   ``id``  = the clipboard identifier
 140
 141   ``seq`` = sequence number. Client must use the sequence number passed in
 142   the most recent barrierCmdCEnter.  the server always sends 0.
 143
 144 barrierCmdCScreenSaver   "CSEC"
 145 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 146
 147 Direction:
 148   server -> client
 149 Parameters:
 150   ``{ int8_t started }``
 151 Description:
 152   Screensaver change.
 153
 154   ``started`` = Screensaver on primary has started (1) or closed (0)
 155
 156 barrierCmdCResetOptions  "CROP"
 157 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 158
 159 Direction:
 160   server -> client
 161 Parameters:
 162   None
 163 Description:
 164   Reset options. Client should reset all of its options to their
 165   defaults.
 166
 167 barrierCmdCInfoAck   "CIAK"
 168 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 169
 170 Direction:
 171   server -> client
 172 Parameters:
 173   None
 174 Description:
 175   Resolution change acknowledgment. Sent by server in response to a
 176   client screen's barrierCmdDInfo. This is sent for every
 177   barrierCmdDInfo, whether or not the server had sent a barrierCmdQInfo.
 178
 179 barrierCmdCKeepAlive "CALV"
 180 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 181
 182 Direction:
 183   server -> client
 184 Parameters:
 185   None
 186 Description:
 187   Keep connection alive. Sent by the server periodically to verify
 188   that connections are still up and running.  clients must reply in
 189   kind on receipt.  if the server gets an error sending the message or
 190   does not receive a reply within a reasonable time then the server
 191   disconnects the client.  if the client doesn't receive these (or any
 192   message) periodically then it should disconnect from the server.  the
 193   appropriate interval is defined by an option.
 194
 195 barrierCmdDKeyDown   "DKDN"
 196 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 197
 198 Direction:
 199   server -> client
 200 Parameters:
 201   ``{ int16_t keyid, int16_t modifier [,int16_t button] }``
 202 Description:
 203   Key pressed.
 204
 205   ``keyid`` = X11 key id
 206
 207   ``modified`` = modified mask
 208
 209   ``button`` = X11 Xkb keycode (optional)
 210
 211 barrierCmdDKeyRepeat "DKRP"
 212 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 213
 214 Direction:
 215   server -> client
 216 Parameters:
 217   ``{ int16_t keyid, int16_t modifier, int16_t repeat [,int16_t button] }``
 218 Description:
 219   Key auto-repeat.
 220
 221   ``keyid`` = X11 key id
 222
 223   ``modified`` = modified mask
 224
 225   ``repeat``   = number of repeats
 226
 227   ``button``   = X11 Xkb keycode (optional)
 228
 229 barrierCmdDKeyUp "DKUP"
 230 ^^^^^^^^^^^^^^^^^^^^^^^
 231
 232 Direction:
 233   server -> client
 234 Parameters:
 235   ``{ int16_t keyid, int16_t modifier [,int16_t button] }``
 236 Description:
 237   Key released.
 238
 239   ``keyid`` = X11 key id
 240
 241   ``modified`` = modified mask
 242
 243   ``button`` = X11 Xkb keycode (optional)
 244
 245 barrierCmdDMouseDown "DMDN"
 246 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 247
 248 Direction:
 249   server -> client
 250 Parameters:
 251   ``{ int8_t button }``
 252 Description:
 253   Mouse button pressed.
 254
 255   ``button`` = button id
 256
 257 barrierCmdDMouseUp   "DMUP"
 258 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 259
 260 Direction:
 261   server -> client
 262 Parameters:
 263   ``{ int8_t button }``
 264 Description:
 265   Mouse button release.
 266
 267   ``button`` = button id
 268
 269 barrierCmdDMouseMove "DMMV"
 270 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 271
 272 Direction:
 273   server -> client
 274 Parameters:
 275   ``{ int16_t x, int16_t y }``
 276 Description:
 277   Absolute mouse moved.
 278
 279   ``x``, ``y`` = absolute screen coordinates
 280
 281 barrierCmdDMouseRelMove  "DMRM"
 282 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 283
 284 Direction:
 285   server -> client
 286 Parameters:
 287   ``{ int16_t x, int16_t y }``
 288 Description:
 289   Relative mouse moved.
 290
 291   ``x``, ``y`` = r relative screen coordinates
 292
 293 barrierCmdDMouseWheel "DMWM"
 294 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 295
 296 Direction:
 297   server -> client
 298 Parameters:
 299   ``{ int16_t x , int16_t y }`` or ``{ int16_t y }``
 300 Description:
 301   Mouse scroll. The delta should be +120 for one tick forward (away
 302   from the user) or right and -120 for one tick backward (toward the
 303   user) or left.
 304
 305   ``x`` = x delta
 306
 307   ``y`` = y delta
 308
 309 barrierCmdDClipboard "DCLP"
 310 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 311
 312 Direction:
 313   server -> client
 314 Parameters:
 315   ``{ int8_t id, int32_t seq, int8_t mark, char *data }``
 316 Description:
 317   Clipboard data.
 318
 319   ``id``  = clipboard id
 320
 321   ``seq`` = sequence number. The sequence number is 0 when sent by the
 322   server.  Client screens should use the/ sequence number from
 323   the most recent barrierCmdCEnter.
 324
 325 barrierCmdDSetOptions "DSOP"
 326 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 327
 328 Direction:
 329   server -> client
 330 Parameters:
 331   ``{ int32 t nb, { int32_t id, int32_t val }[] }``
 332 Description:
 333   Set options. Client should set the given option/value pairs.
 334
 335   ``nb``  = numbers of ``{ id, val }`` entries
 336
 337   ``id``  = option id
 338
 339   ``val`` = option new value
 340
 341 barrierCmdDFileTransfer "DFTR"
 342 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 343
 344 Direction:
 345   server -> client
 346 Parameters:
 347   ``{ int8_t mark, char *content }``
 348 Description:
 349   Transfer file data.
 350
 351   * ``mark`` = 0 means the content followed is the file size
 352   * 1 means the content followed is the chunk data
 353   * 2 means the file transfer is finished
 354
 355 barrierCmdDDragInfo  "DDRG"
 356 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 357
 358 Direction:
 359   server -> client
 360 Parameters:
 361   ``{ int16_t nb, char *content }``
 362 Description:
 363   Drag information.
 364
 365   ``nb``  = number of dragging objects
 366
 367   ``content`` = object's directory
 368
 369 barrierCmdQInfo  "QINF"
 370 ^^^^^^^^^^^^^^^^^^^^^^^
 371
 372 Direction:
 373   server -> client
 374 Parameters:
 375   None
 376 Description:
 377   Query screen info
 378
 379   Client should reply with a barrierCmdDInfo
 380
 381 barrierCmdEIncompatible  "EICV"
 382 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 383
 384 Direction:
 385   server -> client
 386 Parameters:
 387   ``{ int16_t nb, major *minor }``
 388 Description:
 389   Incompatible version.
 390
 391   ``major`` = major version
 392
 393   ``minor`` = minor version
 394
 395 barrierCmdEBusy  "EBSY"
 396 ^^^^^^^^^^^^^^^^^^^^^^^
 397
 398 Direction:
 399   server -> client
 400 Parameters:
 401   None
 402 Description:
 403   Name provided when connecting is already in use.
 404
 405 barrierCmdEUnknown   "EUNK"
 406 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 407
 408 Direction:
 409   server -> client
 410 Parameters:
 411   None
 412 Description:
 413   Unknown client. Name provided when connecting is not in primary's
 414   screen configuration map.
 415
 416 barrierCmdEBad   "EBAD"
 417 ^^^^^^^^^^^^^^^^^^^^^^^
 418
 419 Direction:
 420   server -> client
 421 Parameters:
 422   None
 423 Description:
 424   Protocol violation. Server should disconnect after sending this
 425   message.
 426