1 /* 2 * Copyright (C) 1997, 1998 Olivetti & Oracle Research Laboratory 3 * 4 * This is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU General Public License as published by 6 * the Free Software Foundation; either version 2 of the License, or 7 * (at your option) any later version. 8 * 9 * This software is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 * GNU General Public License for more details. 13 * 14 * You should have received a copy of the GNU General Public License 15 * along with this software; if not, write to the Free Software 16 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, 17 * USA. 18 */ 19 20 /* 21 * rfbproto.h - header file for the RFB protocol version 3.3 22 * 23 * Uses types CARD<n> for an n-bit unsigned integer, INT<n> for an n-bit signed 24 * integer (for n = 8, 16 and 32). 25 * 26 * All multiple byte integers are in big endian (network) order (most 27 * significant byte first). Unless noted otherwise there is no special 28 * alignment of protocol structures. 29 * 30 * 31 * Once the initial handshaking is done, all messages start with a type byte, 32 * (usually) followed by message-specific data. The order of definitions in 33 * this file is as follows: 34 * 35 * (1) Structures used in several types of message. 36 * (2) Structures used in the initial handshaking. 37 * (3) Message types. 38 * (4) Encoding types. 39 * (5) For each message type, the form of the data following the type byte. 40 * Sometimes this is defined by a single structure but the more complex 41 * messages have to be explained by comments. 42 */ 43 44 45 /***************************************************************************** 46 * 47 * Structures used in several messages 48 * 49 *****************************************************************************/ 50 51 /*----------------------------------------------------------------------------- 52 * Structure used to specify a rectangle. This structure is a multiple of 4 53 * bytes so that it can be interspersed with 32-bit pixel data without 54 * affecting alignment. 55 */ 56 57 typedef struct { 58 CARD16 x; 59 CARD16 y; 60 CARD16 w; 61 CARD16 h; 62 } rfbRectangle; 63 64 #define sz_rfbRectangle 8 65 66 67 /*----------------------------------------------------------------------------- 68 * Structure used to specify pixel format. 69 */ 70 71 typedef struct { 72 73 CARD8 bitsPerPixel; /* 8,16,32 only */ 74 75 CARD8 depth; /* 8 to 32 */ 76 77 CARD8 bigEndian; /* True if multi-byte pixels are interpreted 78 as big endian, or if single-bit-per-pixel 79 has most significant bit of the byte 80 corresponding to first (leftmost) pixel. Of 81 course this is meaningless for 8 bits/pix */ 82 83 CARD8 trueColour; /* If false then we need a "colour map" to 84 convert pixels to RGB. If true, xxxMax and 85 xxxShift specify bits used for red, green 86 and blue */ 87 88 /* the following fields are only meaningful if trueColour is true */ 89 90 CARD16 redMax; /* maximum red value (= 2^n - 1 where n is the 91 number of bits used for red). Note this 92 value is always in big endian order. */ 93 94 CARD16 greenMax; /* similar for green */ 95 96 CARD16 blueMax; /* and blue */ 97 98 CARD8 redShift; /* number of shifts needed to get the red 99 value in a pixel to the least significant 100 bit. To find the red value from a given 101 pixel, do the following: 102 1) Swap pixel value according to bigEndian 103 (e.g. if bigEndian is false and host byte 104 order is big endian, then swap). 105 2) Shift right by redShift. 106 3) AND with redMax (in host byte order). 107 4) You now have the red value between 0 and 108 redMax. */ 109 110 CARD8 greenShift; /* similar for green */ 111 112 CARD8 blueShift; /* and blue */ 113 114 CARD8 pad1; 115 CARD16 pad2; 116 117 } rfbPixelFormat; 118 119 #define sz_rfbPixelFormat 16 120 121 122 123 /***************************************************************************** 124 * 125 * Initial handshaking messages 126 * 127 *****************************************************************************/ 128 129 /*----------------------------------------------------------------------------- 130 * Protocol Version 131 * 132 * The server always sends 12 bytes to start which identifies the latest RFB 133 * protocol version number which it supports. These bytes are interpreted 134 * as a string of 12 ASCII characters in the format "RFB xxx.yyy\n" where 135 * xxx and yyy are the major and minor version numbers (for version 3.3 136 * this is "RFB 003.003\n"). 137 * 138 * The client then replies with a similar 12-byte message giving the version 139 * number of the protocol which should actually be used (which may be different 140 * to that quoted by the server). 141 * 142 * It is intended that both clients and servers may provide some level of 143 * backwards compatibility by this mechanism. Servers in particular should 144 * attempt to provide backwards compatibility, and even forwards compatibility 145 * to some extent. For example if a client demands version 3.1 of the 146 * protocol, a 3.0 server can probably assume that by ignoring requests for 147 * encoding types it doesn't understand, everything will still work OK. This 148 * will probably not be the case for changes in the major version number. 149 * 150 * The format string below can be used in sprintf or sscanf to generate or 151 * decode the version string respectively. 152 */ 153 154 #define rfbProtocolVersionFormat "RFB %03d.%03d\n" 155 #define rfbProtocolMajorVersion 3 156 #define rfbProtocolMinorVersion 3 157 158 typedef char rfbProtocolVersionMsg[13]; /* allow extra byte for null */ 159 160 #define sz_rfbProtocolVersionMsg 12 161 162 163 /*----------------------------------------------------------------------------- 164 * Authentication 165 * 166 * Once the protocol version has been decided, the server then sends a 32-bit 167 * word indicating whether any authentication is needed on the connection. 168 * The value of this word determines the authentication scheme in use. For 169 * version 3.0 of the protocol this may have one of the following values: 170 */ 171 172 #define rfbConnFailed 0 173 #define rfbNoAuth 1 174 #define rfbVncAuth 2 175 176 /* 177 * rfbConnFailed: For some reason the connection failed (e.g. the server 178 * cannot support the desired protocol version). This is 179 * followed by a string describing the reason (where a 180 * string is specified as a 32-bit length followed by that 181 * many ASCII characters). 182 * 183 * rfbNoAuth: No authentication is needed. 184 * 185 * rfbVncAuth: The VNC authentication scheme is to be used. A 16-byte 186 * challenge follows, which the client encrypts as 187 * appropriate using the password and sends the resulting 188 * 16-byte response. If the response is correct, the 189 * server sends the 32-bit word rfbVncAuthOK. If a simple 190 * failure happens, the server sends rfbVncAuthFailed and 191 * closes the connection. If the server decides that too 192 * many failures have occurred, it sends rfbVncAuthTooMany 193 * and closes the connection. In the latter case, the 194 * server should not allow an immediate reconnection by 195 * the client. 196 */ 197 198 #define rfbVncAuthOK 0 199 #define rfbVncAuthFailed 1 200 #define rfbVncAuthTooMany 2 201 202 203 /*----------------------------------------------------------------------------- 204 * Client Initialisation Message 205 * 206 * Once the client and server are sure that they're happy to talk to one 207 * another, the client sends an initialisation message. At present this 208 * message only consists of a boolean indicating whether the server should try 209 * to share the desktop by leaving other clients connected, or give exclusive 210 * access to this client by disconnecting all other clients. 211 */ 212 213 typedef struct { 214 CARD8 shared; 215 } rfbClientInitMsg; 216 217 #define sz_rfbClientInitMsg 1 218 219 220 /*----------------------------------------------------------------------------- 221 * Server Initialisation Message 222 * 223 * After the client initialisation message, the server sends one of its own. 224 * This tells the client the width and height of the server's framebuffer, 225 * its pixel format and the name associated with the desktop. 226 */ 227 228 typedef struct { 229 CARD16 framebufferWidth; 230 CARD16 framebufferHeight; 231 rfbPixelFormat format; /* the server's preferred pixel format */ 232 CARD32 nameLength; 233 /* followed by char name[nameLength] */ 234 } rfbServerInitMsg; 235 236 #define sz_rfbServerInitMsg (8 + sz_rfbPixelFormat) 237 238 239 /* 240 * Following the server initialisation message it's up to the client to send 241 * whichever protocol messages it wants. Typically it will send a 242 * SetPixelFormat message and a SetEncodings message, followed by a 243 * FramebufferUpdateRequest. From then on the server will send 244 * FramebufferUpdate messages in response to the client's 245 * FramebufferUpdateRequest messages. The client should send 246 * FramebufferUpdateRequest messages with incremental set to true when it has 247 * finished processing one FramebufferUpdate and is ready to process another. 248 * With a fast client, the rate at which FramebufferUpdateRequests are sent 249 * should be regulated to avoid hogging the network. 250 */ 251 252 253 254 /***************************************************************************** 255 * 256 * Message types 257 * 258 *****************************************************************************/ 259 260 /* server -> client */ 261 262 #define rfbFramebufferUpdate 0 263 #define rfbSetColourMapEntries 1 264 #define rfbBell 2 265 #define rfbServerCutText 3 266 267 268 /* client -> server */ 269 270 #define rfbSetPixelFormat 0 271 #define rfbFixColourMapEntries 1 /* not currently supported */ 272 #define rfbSetEncodings 2 273 #define rfbFramebufferUpdateRequest 3 274 #define rfbKeyEvent 4 275 #define rfbPointerEvent 5 276 #define rfbClientCutText 6 277 278 279 280 281 /***************************************************************************** 282 * 283 * Encoding types 284 * 285 *****************************************************************************/ 286 287 #define rfbEncodingRaw 0 288 #define rfbEncodingCopyRect 1 289 #define rfbEncodingRRE 2 290 #define rfbEncodingCoRRE 4 291 #define rfbEncodingHextile 5 292 293 294 295 /***************************************************************************** 296 * 297 * Server -> client message definitions 298 * 299 *****************************************************************************/ 300 301 302 /*----------------------------------------------------------------------------- 303 * FramebufferUpdate - a block of rectangles to be copied to the framebuffer. 304 * 305 * This message consists of a header giving the number of rectangles of pixel 306 * data followed by the rectangles themselves. The header is padded so that 307 * together with the type byte it is an exact multiple of 4 bytes (to help 308 * with alignment of 32-bit pixels): 309 */ 310 311 typedef struct { 312 CARD8 type; /* always rfbFramebufferUpdate */ 313 CARD8 pad; 314 CARD16 nRects; 315 /* followed by nRects rectangles */ 316 } rfbFramebufferUpdateMsg; 317 318 #define sz_rfbFramebufferUpdateMsg 4 319 320 /* 321 * Each rectangle of pixel data consists of a header describing the position 322 * and size of the rectangle and a type word describing the encoding of the 323 * pixel data, followed finally by the pixel data. Note that if the client has 324 * not sent a SetEncodings message then it will only receive raw pixel data. 325 * Also note again that this structure is a multiple of 4 bytes. 326 */ 327 328 typedef struct { 329 rfbRectangle r; 330 CARD32 encoding; /* one of the encoding types rfbEncoding... */ 331 } rfbFramebufferUpdateRectHeader; 332 333 #define sz_rfbFramebufferUpdateRectHeader (sz_rfbRectangle + 4) 334 335 336 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 337 * Raw Encoding. Pixels are sent in top-to-bottom scanline order, 338 * left-to-right within a scanline with no padding in between. 339 */ 340 341 342 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 343 * CopyRect Encoding. The pixels are specified simply by the x and y position 344 * of the source rectangle. 345 */ 346 347 typedef struct { 348 CARD16 srcX; 349 CARD16 srcY; 350 } rfbCopyRect; 351 352 #define sz_rfbCopyRect 4 353 354 355 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 356 * RRE - Rise-and-Run-length Encoding. We have an rfbRREHeader structure 357 * giving the number of subrectangles following. Finally the data follows in 358 * the form [<bgpixel><subrect><subrect>...] where each <subrect> is 359 * [<pixel><rfbRectangle>]. 360 */ 361 362 typedef struct { 363 CARD32 nSubrects; 364 } rfbRREHeader; 365 366 #define sz_rfbRREHeader 4 367 368 369 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 370 * CoRRE - Compact RRE Encoding. We have an rfbRREHeader structure giving 371 * the number of subrectangles following. Finally the data follows in the form 372 * [<bgpixel><subrect><subrect>...] where each <subrect> is 373 * [<pixel><rfbCoRRERectangle>]. This means that 374 * the whole rectangle must be at most 255x255 pixels. 375 */ 376 377 typedef struct { 378 CARD8 x; 379 CARD8 y; 380 CARD8 w; 381 CARD8 h; 382 } rfbCoRRERectangle; 383 384 #define sz_rfbCoRRERectangle 4 385 386 387 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 388 * Hextile Encoding. The rectangle is divided up into "tiles" of 16x16 pixels, 389 * starting at the top left going in left-to-right, top-to-bottom order. If 390 * the width of the rectangle is not an exact multiple of 16 then the width of 391 * the last tile in each row will be correspondingly smaller. Similarly if the 392 * height is not an exact multiple of 16 then the height of each tile in the 393 * final row will also be smaller. Each tile begins with a "subencoding" type 394 * byte, which is a mask made up of a number of bits. If the Raw bit is set 395 * then the other bits are irrelevant; w*h pixel values follow (where w and h 396 * are the width and height of the tile). Otherwise the tile is encoded in a 397 * similar way to RRE, except that the position and size of each subrectangle 398 * can be specified in just two bytes. The other bits in the mask are as 399 * follows: 400 * 401 * BackgroundSpecified - if set, a pixel value follows which specifies 402 * the background colour for this tile. The first non-raw tile in a 403 * rectangle must have this bit set. If this bit isn't set then the 404 * background is the same as the last tile. 405 * 406 * ForegroundSpecified - if set, a pixel value follows which specifies 407 * the foreground colour to be used for all subrectangles in this tile. 408 * If this bit is set then the SubrectsColoured bit must be zero. 409 * 410 * AnySubrects - if set, a single byte follows giving the number of 411 * subrectangles following. If not set, there are no subrectangles (i.e. 412 * the whole tile is just solid background colour). 413 * 414 * SubrectsColoured - if set then each subrectangle is preceded by a pixel 415 * value giving the colour of that subrectangle. If not set, all 416 * subrectangles are the same colour, the foreground colour; if the 417 * ForegroundSpecified bit wasn't set then the foreground is the same as 418 * the last tile. 419 * 420 * The position and size of each subrectangle is specified in two bytes. The 421 * Pack macros below can be used to generate the two bytes from x, y, w, h, 422 * and the Extract macros can be used to extract the x, y, w, h values from 423 * the two bytes. 424 */ 425 426 #define rfbHextileRaw (1 << 0) 427 #define rfbHextileBackgroundSpecified (1 << 1) 428 #define rfbHextileForegroundSpecified (1 << 2) 429 #define rfbHextileAnySubrects (1 << 3) 430 #define rfbHextileSubrectsColoured (1 << 4) 431 432 #define rfbHextilePackXY(x,y) (((x) << 4) | (y)) 433 #define rfbHextilePackWH(w,h) ((((w)-1) << 4) | ((h)-1)) 434 #define rfbHextileExtractX(byte) ((byte) >> 4) 435 #define rfbHextileExtractY(byte) ((byte) & 0xf) 436 #define rfbHextileExtractW(byte) (((byte) >> 4) + 1) 437 #define rfbHextileExtractH(byte) (((byte) & 0xf) + 1) 438 439 440 /*----------------------------------------------------------------------------- 441 * SetColourMapEntries - these messages are only sent if the pixel 442 * format uses a "colour map" (i.e. trueColour false) and the client has not 443 * fixed the entire colour map using FixColourMapEntries. In addition they 444 * will only start being sent after the client has sent its first 445 * FramebufferUpdateRequest. So if the client always tells the server to use 446 * trueColour then it never needs to process this type of message. 447 */ 448 449 typedef struct { 450 CARD8 type; /* always rfbSetColourMapEntries */ 451 CARD8 pad; 452 CARD16 firstColour; 453 CARD16 nColours; 454 455 /* Followed by nColours * 3 * CARD16 456 r1, g1, b1, r2, g2, b2, r3, g3, b3, ..., rn, bn, gn */ 457 458 } rfbSetColourMapEntriesMsg; 459 460 #define sz_rfbSetColourMapEntriesMsg 6 461 462 463 464 /*----------------------------------------------------------------------------- 465 * Bell - ring a bell on the client if it has one. 466 */ 467 468 typedef struct { 469 CARD8 type; /* always rfbBell */ 470 } rfbBellMsg; 471 472 #define sz_rfbBellMsg 1 473 474 475 476 /*----------------------------------------------------------------------------- 477 * ServerCutText - the server has new text in its cut buffer. 478 */ 479 480 typedef struct { 481 CARD8 type; /* always rfbServerCutText */ 482 CARD8 pad1; 483 CARD16 pad2; 484 CARD32 length; 485 /* followed by char text[length] */ 486 } rfbServerCutTextMsg; 487 488 #define sz_rfbServerCutTextMsg 8 489 490 491 /*----------------------------------------------------------------------------- 492 * Union of all server->client messages. 493 */ 494 495 typedef union { 496 CARD8 type; 497 rfbFramebufferUpdateMsg fu; 498 rfbSetColourMapEntriesMsg scme; 499 rfbBellMsg b; 500 rfbServerCutTextMsg sct; 501 } rfbServerToClientMsg; 502 503 504 505 /***************************************************************************** 506 * 507 * Message definitions (client -> server) 508 * 509 *****************************************************************************/ 510 511 512 /*----------------------------------------------------------------------------- 513 * SetPixelFormat - tell the RFB server the format in which the client wants 514 * pixels sent. 515 */ 516 517 typedef struct { 518 CARD8 type; /* always rfbSetPixelFormat */ 519 CARD8 pad1; 520 CARD16 pad2; 521 rfbPixelFormat format; 522 } rfbSetPixelFormatMsg; 523 524 #define sz_rfbSetPixelFormatMsg (sz_rfbPixelFormat + 4) 525 526 527 /*----------------------------------------------------------------------------- 528 * FixColourMapEntries - when the pixel format uses a "colour map", fix 529 * read-only colour map entries. 530 * 531 * ***************** NOT CURRENTLY SUPPORTED ***************** 532 */ 533 534 typedef struct { 535 CARD8 type; /* always rfbFixColourMapEntries */ 536 CARD8 pad; 537 CARD16 firstColour; 538 CARD16 nColours; 539 540 /* Followed by nColours * 3 * CARD16 541 r1, g1, b1, r2, g2, b2, r3, g3, b3, ..., rn, bn, gn */ 542 543 } rfbFixColourMapEntriesMsg; 544 545 #define sz_rfbFixColourMapEntriesMsg 6 546 547 548 /*----------------------------------------------------------------------------- 549 * SetEncodings - tell the RFB server which encoding types we accept. Put them 550 * in order of preference, if we have any. We may always receive raw 551 * encoding, even if we don't specify it here. 552 */ 553 554 typedef struct { 555 CARD8 type; /* always rfbSetEncodings */ 556 CARD8 pad; 557 CARD16 nEncodings; 558 /* followed by nEncodings * CARD32 encoding types */ 559 } rfbSetEncodingsMsg; 560 561 #define sz_rfbSetEncodingsMsg 4 562 563 564 /*----------------------------------------------------------------------------- 565 * FramebufferUpdateRequest - request for a framebuffer update. If incremental 566 * is true then the client just wants the changes since the last update. If 567 * false then it wants the whole of the specified rectangle. 568 */ 569 570 typedef struct { 571 CARD8 type; /* always rfbFramebufferUpdateRequest */ 572 CARD8 incremental; 573 CARD16 x; 574 CARD16 y; 575 CARD16 w; 576 CARD16 h; 577 } rfbFramebufferUpdateRequestMsg; 578 579 #define sz_rfbFramebufferUpdateRequestMsg 10 580 581 582 /*----------------------------------------------------------------------------- 583 * KeyEvent - key press or release 584 * 585 * Keys are specified using the "keysym" values defined by the X Window System. 586 * For most ordinary keys, the keysym is the same as the corresponding ASCII 587 * value. Other common keys are: 588 * 589 * BackSpace 0xff08 590 * Tab 0xff09 591 * Return or Enter 0xff0d 592 * Escape 0xff1b 593 * Insert 0xff63 594 * Delete 0xffff 595 * Home 0xff50 596 * End 0xff57 597 * Page Up 0xff55 598 * Page Down 0xff56 599 * Left 0xff51 600 * Up 0xff52 601 * Right 0xff53 602 * Down 0xff54 603 * F1 0xffbe 604 * F2 0xffbf 605 * ... ... 606 * F12 0xffc9 607 * Shift 0xffe1 608 * Control 0xffe3 609 * Meta 0xffe7 610 * Alt 0xffe9 611 */ 612 613 typedef struct { 614 CARD8 type; /* always rfbKeyEvent */ 615 CARD8 down; /* true if down (press), false if up */ 616 CARD16 pad; 617 CARD32 key; /* key is specified as an X keysym */ 618 } rfbKeyEventMsg; 619 620 #define sz_rfbKeyEventMsg 8 621 622 623 /*----------------------------------------------------------------------------- 624 * PointerEvent - mouse/pen move and/or button press. 625 */ 626 627 typedef struct { 628 CARD8 type; /* always rfbPointerEvent */ 629 CARD8 buttonMask; /* bits 0-7 are buttons 1-8, 0=up, 1=down */ 630 CARD16 x; 631 CARD16 y; 632 } rfbPointerEventMsg; 633 634 #define rfbButton1Mask 1 635 #define rfbButton2Mask 2 636 #define rfbButton3Mask 4 637 638 #define sz_rfbPointerEventMsg 6 639 640 641 642 /*----------------------------------------------------------------------------- 643 * ClientCutText - the client has new text in its cut buffer. 644 */ 645 646 typedef struct { 647 CARD8 type; /* always rfbClientCutText */ 648 CARD8 pad1; 649 CARD16 pad2; 650 CARD32 length; 651 /* followed by char text[length] */ 652 } rfbClientCutTextMsg; 653 654 #define sz_rfbClientCutTextMsg 8 655 656 657 658 /*----------------------------------------------------------------------------- 659 * Union of all client->server messages. 660 */ 661 662 typedef union { 663 CARD8 type; 664 rfbSetPixelFormatMsg spf; 665 rfbFixColourMapEntriesMsg fcme; 666 rfbSetEncodingsMsg se; 667 rfbFramebufferUpdateRequestMsg fur; 668 rfbKeyEventMsg ke; 669 rfbPointerEventMsg pe; 670 rfbClientCutTextMsg cct; 671 } rfbClientToServerMsg; 672