barrier.rst (9451B)
1Barrier client protocol 2======================= 3 4QEMU's ``input-barrier`` device implements the client end of 5the KVM (Keyboard-Video-Mouse) software 6`Barrier <https://github.com/debauchee/barrier>`__. 7 8This document briefly describes the protocol as we implement it. 9 10Message format 11-------------- 12 13Message 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 18The payload starts with a 4byte string (without NUL) which is the 19command. The first command between the server and the client 20is the only command not encoded on 4 bytes ("Barrier"). 21The remaining part of the payload is decoded according to the command. 22 23Protocol Description 24-------------------- 25 26This comes from ``barrier/src/lib/barrier/protocol_types.h``. 27 28barrierCmdHello "Barrier" 29^^^^^^^^^^^^^^^^^^^^^^^^^^ 30 31Direction: 32 server -> client 33Parameters: 34 ``{ int16_t minor, int16_t major }`` 35Description: 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 42barrierCmdHelloBack "Barrier" 43^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 44 45Direction: 46 client ->server 47Parameters: 48 ``{ int16_t minor, int16_t major, char *name}`` 49Description: 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 58barrierCmdDInfo "DINF" 59^^^^^^^^^^^^^^^^^^^^^^^ 60 61Direction: 62 client ->server 63Parameters: 64 ``{ int16_t x_origin, int16_t y_origin, int16_t width, int16_t height, int16_t x, int16_t y}`` 65Description: 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 73barrierCmdCNoop "CNOP" 74^^^^^^^^^^^^^^^^^^^^^^^ 75 76Direction: 77 client -> server 78Parameters: 79 None 80Description: 81 No operation 82 83barrierCmdCClose "CBYE" 84^^^^^^^^^^^^^^^^^^^^^^^ 85 86Direction: 87 server -> client 88Parameters: 89 None 90Description: 91 Close connection 92 93barrierCmdCEnter "CINN" 94^^^^^^^^^^^^^^^^^^^^^^^ 95 96Direction: 97 server -> client 98Parameters: 99 ``{ int16_t x, int16_t y, int32_t seq, int16_t modifier }`` 100Description: 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 114barrierCmdCLeave "COUT" 115^^^^^^^^^^^^^^^^^^^^^^^ 116 117Direction: 118 server -> client 119Parameters: 120 None 121Description: 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 128barrierCmdCClipboard "CCLP" 129^^^^^^^^^^^^^^^^^^^^^^^^^^^ 130 131Direction: 132 server -> client 133Parameters: 134 ``{ int8_t id, int32_t seq }`` 135Description: 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 144barrierCmdCScreenSaver "CSEC" 145^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 146 147Direction: 148 server -> client 149Parameters: 150 ``{ int8_t started }`` 151Description: 152 Screensaver change. 153 154 ``started`` = Screensaver on primary has started (1) or closed (0) 155 156barrierCmdCResetOptions "CROP" 157^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 158 159Direction: 160 server -> client 161Parameters: 162 None 163Description: 164 Reset options. Client should reset all of its options to their 165 defaults. 166 167barrierCmdCInfoAck "CIAK" 168^^^^^^^^^^^^^^^^^^^^^^^^^^^ 169 170Direction: 171 server -> client 172Parameters: 173 None 174Description: 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 179barrierCmdCKeepAlive "CALV" 180^^^^^^^^^^^^^^^^^^^^^^^^^^^ 181 182Direction: 183 server -> client 184Parameters: 185 None 186Description: 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 195barrierCmdDKeyDown "DKDN" 196^^^^^^^^^^^^^^^^^^^^^^^^^^^ 197 198Direction: 199 server -> client 200Parameters: 201 ``{ int16_t keyid, int16_t modifier [,int16_t button] }`` 202Description: 203 Key pressed. 204 205 ``keyid`` = X11 key id 206 207 ``modified`` = modified mask 208 209 ``button`` = X11 Xkb keycode (optional) 210 211barrierCmdDKeyRepeat "DKRP" 212^^^^^^^^^^^^^^^^^^^^^^^^^^^ 213 214Direction: 215 server -> client 216Parameters: 217 ``{ int16_t keyid, int16_t modifier, int16_t repeat [,int16_t button] }`` 218Description: 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 229barrierCmdDKeyUp "DKUP" 230^^^^^^^^^^^^^^^^^^^^^^^ 231 232Direction: 233 server -> client 234Parameters: 235 ``{ int16_t keyid, int16_t modifier [,int16_t button] }`` 236Description: 237 Key released. 238 239 ``keyid`` = X11 key id 240 241 ``modified`` = modified mask 242 243 ``button`` = X11 Xkb keycode (optional) 244 245barrierCmdDMouseDown "DMDN" 246^^^^^^^^^^^^^^^^^^^^^^^^^^^ 247 248Direction: 249 server -> client 250Parameters: 251 ``{ int8_t button }`` 252Description: 253 Mouse button pressed. 254 255 ``button`` = button id 256 257barrierCmdDMouseUp "DMUP" 258^^^^^^^^^^^^^^^^^^^^^^^^^^^ 259 260Direction: 261 server -> client 262Parameters: 263 ``{ int8_t button }`` 264Description: 265 Mouse button release. 266 267 ``button`` = button id 268 269barrierCmdDMouseMove "DMMV" 270^^^^^^^^^^^^^^^^^^^^^^^^^^^ 271 272Direction: 273 server -> client 274Parameters: 275 ``{ int16_t x, int16_t y }`` 276Description: 277 Absolute mouse moved. 278 279 ``x``, ``y`` = absolute screen coordinates 280 281barrierCmdDMouseRelMove "DMRM" 282^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 283 284Direction: 285 server -> client 286Parameters: 287 ``{ int16_t x, int16_t y }`` 288Description: 289 Relative mouse moved. 290 291 ``x``, ``y`` = r relative screen coordinates 292 293barrierCmdDMouseWheel "DMWM" 294^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 295 296Direction: 297 server -> client 298Parameters: 299 ``{ int16_t x , int16_t y }`` or ``{ int16_t y }`` 300Description: 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 309barrierCmdDClipboard "DCLP" 310^^^^^^^^^^^^^^^^^^^^^^^^^^^ 311 312Direction: 313 server -> client 314Parameters: 315 ``{ int8_t id, int32_t seq, int8_t mark, char *data }`` 316Description: 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 325barrierCmdDSetOptions "DSOP" 326^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 327 328Direction: 329 server -> client 330Parameters: 331 ``{ int32 t nb, { int32_t id, int32_t val }[] }`` 332Description: 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 341barrierCmdDFileTransfer "DFTR" 342^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 343 344Direction: 345 server -> client 346Parameters: 347 ``{ int8_t mark, char *content }`` 348Description: 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 355barrierCmdDDragInfo "DDRG" 356^^^^^^^^^^^^^^^^^^^^^^^^^^^ 357 358Direction: 359 server -> client 360Parameters: 361 ``{ int16_t nb, char *content }`` 362Description: 363 Drag information. 364 365 ``nb`` = number of dragging objects 366 367 ``content`` = object's directory 368 369barrierCmdQInfo "QINF" 370^^^^^^^^^^^^^^^^^^^^^^^ 371 372Direction: 373 server -> client 374Parameters: 375 None 376Description: 377 Query screen info 378 379 Client should reply with a barrierCmdDInfo 380 381barrierCmdEIncompatible "EICV" 382^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 383 384Direction: 385 server -> client 386Parameters: 387 ``{ int16_t nb, major *minor }`` 388Description: 389 Incompatible version. 390 391 ``major`` = major version 392 393 ``minor`` = minor version 394 395barrierCmdEBusy "EBSY" 396^^^^^^^^^^^^^^^^^^^^^^^ 397 398Direction: 399 server -> client 400Parameters: 401 None 402Description: 403 Name provided when connecting is already in use. 404 405barrierCmdEUnknown "EUNK" 406^^^^^^^^^^^^^^^^^^^^^^^^^^^ 407 408Direction: 409 server -> client 410Parameters: 411 None 412Description: 413 Unknown client. Name provided when connecting is not in primary's 414 screen configuration map. 415 416barrierCmdEBad "EBAD" 417^^^^^^^^^^^^^^^^^^^^^^^ 418 419Direction: 420 server -> client 421Parameters: 422 None 423Description: 424 Protocol violation. Server should disconnect after sending this 425 message. 426