barrier.rst (9451B)
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