krdc/vnc/rfbproto.h

   1 /*
   2  *  Copyright 2000-2002 Constantin Kaplinsky. <const@ce.cctpu.edu.ru>
   3  *  Copyright 2000 Tridia Corporation.  All Rights Reserved.
   4  *  Copyright 1999 AT&T Laboratories Cambridge.  All Rights Reserved.
   5  *
   6  *  This is free software; you can redistribute it and/or modify
   7  *  it under the terms of the GNU General Public License as published by
   8  *  the Free Software Foundation; either version 2 of the License, or
   9  *  (at your option) any later version.
  10  *
  11  *  This software is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License
  17  *  along with this software; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
  19  *  USA.
  20  */
  21
  22 /*
  23  * rfbproto.h - header file for the RFB protocol version 3.3
  24  *
  25  * Uses types CARD<n> for an n-bit unsigned integer, INT<n> for an n-bit signed
  26  * integer (for n = 8, 16 and 32).
  27  *
  28  * All multiple byte integers are in big endian (network) order (most
  29  * significant byte first).  Unless noted otherwise there is no special
  30  * alignment of protocol structures.
  31  *
  32  *
  33  * Once the initial handshaking is done, all messages start with a type byte,
  34  * (usually) followed by message-specific data.  The order of definitions in
  35  * this file is as follows:
  36  *
  37  *  (1) Structures used in several types of message.
  38  *  (2) Structures used in the initial handshaking.
  39  *  (3) Message types.
  40  *  (4) Encoding types.
  41  *  (5) For each message type, the form of the data following the type byte.
  42  *      Sometimes this is defined by a single structure but the more complex
  43  *      messages have to be explained by comments.
  44  */
  45
  46 #include "vnctypes.h"
  47
  48 /*****************************************************************************
  49  *
  50  * Structures used in several messages
  51  *
  52  *****************************************************************************/
  53
  54 /*-----------------------------------------------------------------------------
  55  * Structure used to specify a rectangle.  This structure is a multiple of 4
  56  * bytes so that it can be interspersed with 32-bit pixel data without
  57  * affecting alignment.
  58  */
  59
  60 typedef struct {
  61     CARD16 x;
  62     CARD16 y;
  63     CARD16 w;
  64     CARD16 h;
  65 } rfbRectangle;
  66
  67 #define sz_rfbRectangle 8
  68
  69
  70 /*-----------------------------------------------------------------------------
  71  * Structure used to specify pixel format.
  72  */
  73
  74 typedef struct {
  75
  76     CARD8 bitsPerPixel;         /* 8,16,32 only */
  77
  78     CARD8 depth;                /* 8 to 32 */
  79
  80     CARD8 bigEndian;            /* True if multi-byte pixels are interpreted
  81                                    as big endian, or if single-bit-per-pixel
  82                                    has most significant bit of the byte
  83                                    corresponding to first (leftmost) pixel. Of
  84                                    course this is meaningless for 8 bits/pix */
  85
  86     CARD8 trueColour;           /* If false then we need a "colour map" to
  87                                    convert pixels to RGB.  If true, xxxMax and
  88                                    xxxShift specify bits used for red, green
  89                                    and blue */
  90
  91     /* the following fields are only meaningful if trueColour is true */
  92
  93     CARD16 redMax;              /* maximum red value (= 2^n - 1 where n is the
  94                                    number of bits used for red). Note this
  95                                    value is always in big endian order. */
  96
  97     CARD16 greenMax;            /* similar for green */
  98
  99     CARD16 blueMax;             /* and blue */
 100
 101     CARD8 redShift;             /* number of shifts needed to get the red
 102                                    value in a pixel to the least significant
 103                                    bit. To find the red value from a given
 104                                    pixel, do the following:
 105                                    1) Swap pixel value according to bigEndian
 106                                       (e.g. if bigEndian is false and host byte
 107                                       order is big endian, then swap).
 108                                    2) Shift right by redShift.
 109                                    3) AND with redMax (in host byte order).
 110                                    4) You now have the red value between 0 and
 111                                       redMax. */
 112
 113     CARD8 greenShift;           /* similar for green */
 114
 115     CARD8 blueShift;            /* and blue */
 116
 117     CARD8 pad1;
 118     CARD16 pad2;
 119
 120 } rfbPixelFormat;
 121
 122 #define sz_rfbPixelFormat 16
 123
 124
 125
 126 /*****************************************************************************
 127  *
 128  * Initial handshaking messages
 129  *
 130  *****************************************************************************/
 131
 132 /*-----------------------------------------------------------------------------
 133  * Protocol Version
 134  *
 135  * The server always sends 12 bytes to start which identifies the latest RFB
 136  * protocol version number which it supports.  These bytes are interpreted
 137  * as a string of 12 ASCII characters in the format "RFB xxx.yyy\n" where
 138  * xxx and yyy are the major and minor version numbers (for version 3.3
 139  * this is "RFB 003.003\n").
 140  *
 141  * The client then replies with a similar 12-byte message giving the version
 142  * number of the protocol which should actually be used (which may be different
 143  * to that quoted by the server).
 144  *
 145  * It is intended that both clients and servers may provide some level of
 146  * backwards compatibility by this mechanism.  Servers in particular should
 147  * attempt to provide backwards compatibility, and even forwards compatibility
 148  * to some extent.  For example if a client demands version 3.1 of the
 149  * protocol, a 3.0 server can probably assume that by ignoring requests for
 150  * encoding types it doesn't understand, everything will still work OK.  This
 151  * will probably not be the case for changes in the major version number.
 152  *
 153  * The format string below can be used in sprintf or sscanf to generate or
 154  * decode the version string respectively.
 155  */
 156
 157 #define rfbProtocolVersionFormat "RFB %03d.%03d\n"
 158 #define rfbProtocolMajorVersion 3
 159 #define rfbProtocolMinorVersion 3
 160
 161 typedef char rfbProtocolVersionMsg[13]; /* allow extra byte for null */
 162
 163 #define sz_rfbProtocolVersionMsg 12
 164
 165
 166 /*-----------------------------------------------------------------------------
 167  * Authentication
 168  *
 169  * Once the protocol version has been decided, the server then sends a 32-bit
 170  * word indicating whether any authentication is needed on the connection.
 171  * The value of this word determines the authentication scheme in use.  For
 172  * version 3.0 of the protocol this may have one of the following values:
 173  */
 174
 175 #define rfbConnFailed 0
 176 #define rfbNoAuth 1
 177 #define rfbVncAuth 2
 178
 179 /*
 180  * rfbConnFailed:       For some reason the connection failed (e.g. the server
 181  *                      cannot support the desired protocol version).  This is
 182  *                      followed by a string describing the reason (where a
 183  *                      string is specified as a 32-bit length followed by that
 184  *                      many ASCII characters).
 185  *
 186  * rfbNoAuth:           No authentication is needed.
 187  *
 188  * rfbVncAuth:          The VNC authentication scheme is to be used.  A 16-byte
 189  *                      challenge follows, which the client encrypts as
 190  *                      appropriate using the password and sends the resulting
 191  *                      16-byte response.  If the response is correct, the
 192  *                      server sends the 32-bit word rfbVncAuthOK.  If a simple
 193  *                      failure happens, the server sends rfbVncAuthFailed and
 194  *                      closes the connection. If the server decides that too
 195  *                      many failures have occurred, it sends rfbVncAuthTooMany
 196  *                      and closes the connection.  In the latter case, the
 197  *                      server should not allow an immediate reconnection by
 198  *                      the client.
 199  */
 200
 201 #define rfbVncAuthOK 0
 202 #define rfbVncAuthFailed 1
 203 #define rfbVncAuthTooMany 2
 204
 205
 206 /*-----------------------------------------------------------------------------
 207  * Client Initialisation Message
 208  *
 209  * Once the client and server are sure that they're happy to talk to one
 210  * another, the client sends an initialisation message.  At present this
 211  * message only consists of a boolean indicating whether the server should try
 212  * to share the desktop by leaving other clients connected, or give exclusive
 213  * access to this client by disconnecting all other clients.
 214  */
 215
 216 typedef struct {
 217     CARD8 shared;
 218 } rfbClientInitMsg;
 219
 220 #define sz_rfbClientInitMsg 1
 221
 222
 223 /*-----------------------------------------------------------------------------
 224  * Server Initialisation Message
 225  *
 226  * After the client initialisation message, the server sends one of its own.
 227  * This tells the client the width and height of the server's framebuffer,
 228  * its pixel format and the name associated with the desktop.
 229  */
 230
 231 typedef struct {
 232     CARD16 framebufferWidth;
 233     CARD16 framebufferHeight;
 234     rfbPixelFormat format;      /* the server's preferred pixel format */
 235     CARD32 nameLength;
 236     /* followed by char name[nameLength] */
 237 } rfbServerInitMsg;
 238
 239 #define sz_rfbServerInitMsg (8 + sz_rfbPixelFormat)
 240
 241
 242 /*
 243  * Following the server initialisation message it's up to the client to send
 244  * whichever protocol messages it wants.  Typically it will send a
 245  * SetPixelFormat message and a SetEncodings message, followed by a
 246  * FramebufferUpdateRequest.  From then on the server will send
 247  * FramebufferUpdate messages in response to the client's
 248  * FramebufferUpdateRequest messages.  The client should send
 249  * FramebufferUpdateRequest messages with incremental set to true when it has
 250  * finished processing one FramebufferUpdate and is ready to process another.
 251  * With a fast client, the rate at which FramebufferUpdateRequests are sent
 252  * should be regulated to avoid hogging the network.
 253  */
 254
 255
 256
 257 /*****************************************************************************
 258  *
 259  * Message types
 260  *
 261  *****************************************************************************/
 262
 263 /* server -> client */
 264
 265 #define rfbFramebufferUpdate 0
 266 #define rfbSetColourMapEntries 1
 267 #define rfbBell 2
 268 #define rfbServerCutText 3
 269
 270
 271 /* client -> server */
 272
 273 #define rfbSetPixelFormat 0
 274 #define rfbFixColourMapEntries 1        /* not currently supported */
 275 #define rfbSetEncodings 2
 276 #define rfbFramebufferUpdateRequest 3
 277 #define rfbKeyEvent 4
 278 #define rfbPointerEvent 5
 279 #define rfbClientCutText 6
 280
 281
 282
 283
 284 /*****************************************************************************
 285  *
 286  * Encoding types
 287  *
 288  *****************************************************************************/
 289
 290 #define rfbEncodingRaw 0
 291 #define rfbEncodingCopyRect 1
 292 #define rfbEncodingRRE 2
 293 #define rfbEncodingCoRRE 4
 294 #define rfbEncodingHextile 5
 295 #define rfbEncodingZlib 6
 296 #define rfbEncodingTight 7
 297 #define rfbEncodingZlibHex 8
 298
 299 /*
 300  * Special encoding numbers:
 301  *   0xFFFFFF00 .. 0xFFFFFF0F -- encoding-specific compression levels;
 302  *   0xFFFFFF10 .. 0xFFFFFF1F -- mouse cursor shape data;
 303  *   0xFFFFFF20 .. 0xFFFFFF2F -- various protocol extensions;
 304  *   0xFFFFFF30 .. 0xFFFFFFDF -- not allocated yet;
 305  *   0xFFFFFFE0 .. 0xFFFFFFEF -- quality level for JPEG compressor;
 306  *   0xFFFFFFF0 .. 0xFFFFFFFF -- cross-encoding compression levels.
 307  */
 308
 309 #define rfbEncodingCompressLevel0  0xFFFFFF00
 310 #define rfbEncodingCompressLevel1  0xFFFFFF01
 311 #define rfbEncodingCompressLevel2  0xFFFFFF02
 312 #define rfbEncodingCompressLevel3  0xFFFFFF03
 313 #define rfbEncodingCompressLevel4  0xFFFFFF04
 314 #define rfbEncodingCompressLevel5  0xFFFFFF05
 315 #define rfbEncodingCompressLevel6  0xFFFFFF06
 316 #define rfbEncodingCompressLevel7  0xFFFFFF07
 317 #define rfbEncodingCompressLevel8  0xFFFFFF08
 318 #define rfbEncodingCompressLevel9  0xFFFFFF09
 319
 320 #define rfbEncodingXCursor         0xFFFFFF10
 321 #define rfbEncodingRichCursor      0xFFFFFF11
 322 #define rfbEncodingSoftCursor      0xFFFFFF12
 323 #define rfbEncodingPointerPos      0xFFFFFF18
 324
 325 #define rfbEncodingLastRect        0xFFFFFF20
 326 #define rfbEncodingBackground      0xFFFFFF25
 327
 328 #define rfbEncodingQualityLevel0   0xFFFFFFE0
 329 #define rfbEncodingQualityLevel1   0xFFFFFFE1
 330 #define rfbEncodingQualityLevel2   0xFFFFFFE2
 331 #define rfbEncodingQualityLevel3   0xFFFFFFE3
 332 #define rfbEncodingQualityLevel4   0xFFFFFFE4
 333 #define rfbEncodingQualityLevel5   0xFFFFFFE5
 334 #define rfbEncodingQualityLevel6   0xFFFFFFE6
 335 #define rfbEncodingQualityLevel7   0xFFFFFFE7
 336 #define rfbEncodingQualityLevel8   0xFFFFFFE8
 337 #define rfbEncodingQualityLevel9   0xFFFFFFE9
 338
 339
 340 /*****************************************************************************
 341  *
 342  * Server -> client message definitions
 343  *
 344  *****************************************************************************/
 345
 346
 347 /*-----------------------------------------------------------------------------
 348  * FramebufferUpdate - a block of rectangles to be copied to the framebuffer.
 349  *
 350  * This message consists of a header giving the number of rectangles of pixel
 351  * data followed by the rectangles themselves.  The header is padded so that
 352  * together with the type byte it is an exact multiple of 4 bytes (to help
 353  * with alignment of 32-bit pixels):
 354  */
 355
 356 typedef struct {
 357     CARD8 type;                 /* always rfbFramebufferUpdate */
 358     CARD8 pad;
 359     CARD16 nRects;
 360     /* followed by nRects rectangles */
 361 } rfbFramebufferUpdateMsg;
 362
 363 #define sz_rfbFramebufferUpdateMsg 4
 364
 365 /*
 366  * Each rectangle of pixel data consists of a header describing the position
 367  * and size of the rectangle and a type word describing the encoding of the
 368  * pixel data, followed finally by the pixel data.  Note that if the client has
 369  * not sent a SetEncodings message then it will only receive raw pixel data.
 370  * Also note again that this structure is a multiple of 4 bytes.
 371  */
 372
 373 typedef struct {
 374     rfbRectangle r;
 375     CARD32 encoding;    /* one of the encoding types rfbEncoding... */
 376 } rfbFramebufferUpdateRectHeader;
 377
 378 #define sz_rfbFramebufferUpdateRectHeader (sz_rfbRectangle + 4)
 379
 380
 381 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 382  * Raw Encoding.  Pixels are sent in top-to-bottom scanline order,
 383  * left-to-right within a scanline with no padding in between.
 384  */
 385
 386
 387 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 388  * CopyRect Encoding.  The pixels are specified simply by the x and y position
 389  * of the source rectangle.
 390  */
 391
 392 typedef struct {
 393     CARD16 srcX;
 394     CARD16 srcY;
 395 } rfbCopyRect;
 396
 397 #define sz_rfbCopyRect 4
 398
 399
 400 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 401  * RRE - Rise-and-Run-length Encoding.  We have an rfbRREHeader structure
 402  * giving the number of subrectangles following.  Finally the data follows in
 403  * the form [<bgpixel><subrect><subrect>...] where each <subrect> is
 404  * [<pixel><rfbRectangle>].
 405  */
 406
 407 typedef struct {
 408     CARD32 nSubrects;
 409 } rfbRREHeader;
 410
 411 #define sz_rfbRREHeader 4
 412
 413
 414 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 415  * CoRRE - Compact RRE Encoding.  We have an rfbRREHeader structure giving
 416  * the number of subrectangles following.  Finally the data follows in the form
 417  * [<bgpixel><subrect><subrect>...] where each <subrect> is
 418  * [<pixel><rfbCoRRERectangle>].  This means that
 419  * the whole rectangle must be at most 255x255 pixels.
 420  */
 421
 422 typedef struct {
 423     CARD8 x;
 424     CARD8 y;
 425     CARD8 w;
 426     CARD8 h;
 427 } rfbCoRRERectangle;
 428
 429 #define sz_rfbCoRRERectangle 4
 430
 431
 432 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 433  * Hextile Encoding.  The rectangle is divided up into "tiles" of 16x16 pixels,
 434  * starting at the top left going in left-to-right, top-to-bottom order.  If
 435  * the width of the rectangle is not an exact multiple of 16 then the width of
 436  * the last tile in each row will be correspondingly smaller.  Similarly if the
 437  * height is not an exact multiple of 16 then the height of each tile in the
 438  * final row will also be smaller.  Each tile begins with a "subencoding" type
 439  * byte, which is a mask made up of a number of bits.  If the Raw bit is set
 440  * then the other bits are irrelevant; w*h pixel values follow (where w and h
 441  * are the width and height of the tile).  Otherwise the tile is encoded in a
 442  * similar way to RRE, except that the position and size of each subrectangle
 443  * can be specified in just two bytes.  The other bits in the mask are as
 444  * follows:
 445  *
 446  * BackgroundSpecified - if set, a pixel value follows which specifies
 447  *    the background colour for this tile.  The first non-raw tile in a
 448  *    rectangle must have this bit set.  If this bit isn't set then the
 449  *    background is the same as the last tile.
 450  *
 451  * ForegroundSpecified - if set, a pixel value follows which specifies
 452  *    the foreground colour to be used for all subrectangles in this tile.
 453  *    If this bit is set then the SubrectsColoured bit must be zero.
 454  *
 455  * AnySubrects - if set, a single byte follows giving the number of
 456  *    subrectangles following.  If not set, there are no subrectangles (i.e.
 457  *    the whole tile is just solid background colour).
 458  *
 459  * SubrectsColoured - if set then each subrectangle is preceded by a pixel
 460  *    value giving the colour of that subrectangle.  If not set, all
 461  *    subrectangles are the same colour, the foreground colour;  if the
 462  *    ForegroundSpecified bit wasn't set then the foreground is the same as
 463  *    the last tile.
 464  *
 465  * The position and size of each subrectangle is specified in two bytes.  The
 466  * Pack macros below can be used to generate the two bytes from x, y, w, h,
 467  * and the Extract macros can be used to extract the x, y, w, h values from
 468  * the two bytes.
 469  */
 470
 471 #define rfbHextileRaw                   (1 << 0)
 472 #define rfbHextileBackgroundSpecified   (1 << 1)
 473 #define rfbHextileForegroundSpecified   (1 << 2)
 474 #define rfbHextileAnySubrects           (1 << 3)
 475 #define rfbHextileSubrectsColoured      (1 << 4)
 476
 477 #define rfbHextilePackXY(x,y) (((x) << 4) | (y))
 478 #define rfbHextilePackWH(w,h) ((((w)-1) << 4) | ((h)-1))
 479 #define rfbHextileExtractX(byte) ((byte) >> 4)
 480 #define rfbHextileExtractY(byte) ((byte) & 0xf)
 481 #define rfbHextileExtractW(byte) (((byte) >> 4) + 1)
 482 #define rfbHextileExtractH(byte) (((byte) & 0xf) + 1)
 483
 484
 485 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 486  * zlib - zlib compressed Encoding.  We have an rfbZlibHeader structure
 487  * giving the number of bytes following.  Finally the data follows is
 488  * zlib compressed version of the raw pixel data as negotiated.
 489  */
 490
 491 typedef struct {
 492     CARD32 nBytes;
 493 } rfbZlibHeader;
 494
 495 #define sz_rfbZlibHeader 4
 496
 497
 498 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 499  * Tight Encoding.
 500  *
 501  *-- The first byte of each Tight-encoded rectangle is a "compression control
 502  *   byte". Its format is as follows (bit 0 is the least significant one):
 503  *
 504  *   bit 0:    if 1, then compression stream 0 should be reset;
 505  *   bit 1:    if 1, then compression stream 1 should be reset;
 506  *   bit 2:    if 1, then compression stream 2 should be reset;
 507  *   bit 3:    if 1, then compression stream 3 should be reset;
 508  *   bits 7-4: if 1000 (0x08), then the compression type is "fill",
 509  *             if 1001 (0x09), then the compression type is "jpeg",
 510  *             if 0xxx, then the compression type is "basic",
 511  *             values greater than 1001 are not valid.
 512  *
 513  * If the compression type is "basic", then bits 6..4 of the
 514  * compression control byte (those xxx in 0xxx) specify the following:
 515  *
 516  *   bits 5-4:  decimal representation is the index of a particular zlib
 517  *              stream which should be used for decompressing the data;
 518  *   bit 6:     if 1, then a "filter id" byte is following this byte.
 519  *
 520  *-- The data that follows after the compression control byte described
 521  * above depends on the compression type ("fill", "jpeg" or "basic").
 522  *
 523  *-- If the compression type is "fill", then the only pixel value follows, in
 524  * client pixel format (see NOTE 1). This value applies to all pixels of the
 525  * rectangle.
 526  *
 527  *-- If the compression type is "jpeg", the following data stream looks like
 528  * this:
 529  *
 530  *   1..3 bytes:  data size (N) in compact representation;
 531  *   N bytes:     JPEG image.
 532  *
 533  * Data size is compactly represented in one, two or three bytes, according
 534  * to the following scheme:
 535  *
 536  *  0xxxxxxx                    (for values 0..127)
 537  *  1xxxxxxx 0yyyyyyy           (for values 128..16383)
 538  *  1xxxxxxx 1yyyyyyy zzzzzzzz  (for values 16384..4194303)
 539  *
 540  * Here each character denotes one bit, xxxxxxx are the least significant 7
 541  * bits of the value (bits 0-6), yyyyyyy are bits 7-13, and zzzzzzzz are the
 542  * most significant 8 bits (bits 14-21). For example, decimal value 10000
 543  * should be represented as two bytes: binary 10010000 01001110, or
 544  * hexadecimal 90 4E.
 545  *
 546  *-- If the compression type is "basic" and bit 6 of the compression control
 547  * byte was set to 1, then the next (second) byte specifies "filter id" which
 548  * tells the decoder what filter type was used by the encoder to pre-process
 549  * pixel data before the compression. The "filter id" byte can be one of the
 550  * following:
 551  *
 552  *   0:  no filter ("copy" filter);
 553  *   1:  "palette" filter;
 554  *   2:  "gradient" filter.
 555  *
 556  *-- If bit 6 of the compression control byte is set to 0 (no "filter id"
 557  * byte), or if the filter id is 0, then raw pixel values in the client
 558  * format (see NOTE 1) will be compressed. See below details on the
 559  * compression.
 560  *
 561  *-- The "gradient" filter pre-processes pixel data with a simple algorithm
 562  * which converts each color component to a difference between a "predicted"
 563  * intensity and the actual intensity. Such a technique does not affect
 564  * uncompressed data size, but helps to compress photo-like images better.
 565  * Pseudo-code for converting intensities to differences is the following:
 566  *
 567  *   P[i,j] := V[i-1,j] + V[i,j-1] - V[i-1,j-1];
 568  *   if (P[i,j] < 0) then P[i,j] := 0;
 569  *   if (P[i,j] > MAX) then P[i,j] := MAX;
 570  *   D[i,j] := V[i,j] - P[i,j];
 571  *
 572  * Here V[i,j] is the intensity of a color component for a pixel at
 573  * coordinates (i,j). MAX is the maximum value of intensity for a color
 574  * component.
 575  *
 576  *-- The "palette" filter converts true-color pixel data to indexed colors
 577  * and a palette which can consist of 2..256 colors. If the number of colors
 578  * is 2, then each pixel is encoded in 1 bit, otherwise 8 bits is used to
 579  * encode one pixel. 1-bit encoding is performed such way that the most
 580  * significant bits correspond to the leftmost pixels, and each raw of pixels
 581  * is aligned to the byte boundary. When "palette" filter is used, the
 582  * palette is sent before the pixel data. The palette begins with an unsigned
 583  * byte which value is the number of colors in the palette minus 1 (i.e. 1
 584  * means 2 colors, 255 means 256 colors in the palette). Then follows the
 585  * palette itself which consist of pixel values in client pixel format (see
 586  * NOTE 1).
 587  *
 588  *-- The pixel data is compressed using the zlib library. But if the data
 589  * size after applying the filter but before the compression is less then 12,
 590  * then the data is sent as is, uncompressed. Four separate zlib streams
 591  * (0..3) can be used and the decoder should read the actual stream id from
 592  * the compression control byte (see NOTE 2).
 593  *
 594  * If the compression is not used, then the pixel data is sent as is,
 595  * otherwise the data stream looks like this:
 596  *
 597  *   1..3 bytes:  data size (N) in compact representation;
 598  *   N bytes:     zlib-compressed data.
 599  *
 600  * Data size is compactly represented in one, two or three bytes, just like
 601  * in the "jpeg" compression method (see above).
 602  *
 603  *-- NOTE 1. If the color depth is 24, and all three color components are
 604  * 8-bit wide, then one pixel in Tight encoding is always represented by
 605  * three bytes, where the first byte is red component, the second byte is
 606  * green component, and the third byte is blue component of the pixel color
 607  * value. This applies to colors in palettes as well.
 608  *
 609  *-- NOTE 2. The decoder must reset compression streams' states before
 610  * decoding the rectangle, if some of bits 0,1,2,3 in the compression control
 611  * byte are set to 1. Note that the decoder must reset zlib streams even if
 612  * the compression type is "fill" or "jpeg".
 613  *
 614  *-- NOTE 3. The "gradient" filter and "jpeg" compression may be used only
 615  * when bits-per-pixel value is either 16 or 32, not 8.
 616  *
 617  *-- NOTE 4. The width of any Tight-encoded rectangle cannot exceed 2048
 618  * pixels. If a rectangle is wider, it must be split into several rectangles
 619  * and each one should be encoded separately.
 620  *
 621  */
 622
 623 #define rfbTightExplicitFilter         0x04
 624 #define rfbTightFill                   0x08
 625 #define rfbTightJpeg                   0x09
 626 #define rfbTightMaxSubencoding         0x09
 627
 628 /* Filters to improve compression efficiency */
 629 #define rfbTightFilterCopy             0x00
 630 #define rfbTightFilterPalette          0x01
 631 #define rfbTightFilterGradient         0x02
 632
 633
 634 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 635  * XCursor encoding. This is a special encoding used to transmit X-style
 636  * cursor shapes from server to clients. Note that for this encoding,
 637  * coordinates in rfbFramebufferUpdateRectHeader structure hold hotspot
 638  * position (r.x, r.y) and cursor size (r.w, r.h). If (w * h != 0), two RGB
 639  * samples are sent after header in the rfbXCursorColors structure. They
 640  * denote foreground and background colors of the cursor. If a client
 641  * supports only black-and-white cursors, it should ignore these colors and
 642  * assume that foreground is black and background is white. Next, two bitmaps
 643  * (1 bits per pixel) follow: first one with actual data (value 0 denotes
 644  * background color, value 1 denotes foreground color), second one with
 645  * transparency data (bits with zero value mean that these pixels are
 646  * transparent). Both bitmaps represent cursor data in a byte stream, from
 647  * left to right, from top to bottom, and each row is byte-aligned. Most
 648  * significant bits correspond to leftmost pixels. The number of bytes in
 649  * each row can be calculated as ((w + 7) / 8). If (w * h == 0), cursor
 650  * should be hidden (or default local cursor should be set by the client).
 651  */
 652
 653 typedef struct {
 654     CARD8 foreRed;
 655     CARD8 foreGreen;
 656     CARD8 foreBlue;
 657     CARD8 backRed;
 658     CARD8 backGreen;
 659     CARD8 backBlue;
 660 } rfbXCursorColors;
 661
 662 #define sz_rfbXCursorColors 6
 663
 664
 665 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 666  * RichCursor encoding. This is a special encoding used to transmit cursor
 667  * shapes from server to clients. It is similar to the XCursor encoding but
 668  * uses client pixel format instead of two RGB colors to represent cursor
 669  * image. For this encoding, coordinates in rfbFramebufferUpdateRectHeader
 670  * structure hold hotspot position (r.x, r.y) and cursor size (r.w, r.h).
 671  * After header, two pixmaps follow: first one with cursor image in current
 672  * client pixel format (like in raw encoding), second with transparency data
 673  * (1 bit per pixel, exactly the same format as used for transparency bitmap
 674  * in the XCursor encoding). If (w * h == 0), cursor should be hidden (or
 675  * default local cursor should be set by the client).
 676  */
 677
 678
 679 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 680  * SoftCursor encoding. This encoding is used to transmit image and position
 681  * of the remote cursor. It has two sub-messages: SetImage is used to upload
 682  * one of 16 images, and Move selects the image and sets the position of the
 683  * cursor.
 684  * Each SoftCursor message starts with a CARD8. If it is in the 0-15 range
 685  * it specifies the number of the cursor image and is followed by the
 686  * rfbSoftCursorMove message. If the given cursor has not been set yet the
 687  * message will be ignored. If the first CARD8 is in the 128-143 range it
 688  * specifies the cursor that will be set in the following
 689  * rfbSoftCursorSetImage message. To hide the cursor send a SetImage
 690  * message with width and height 0 and imageLength 0.
 691  * SetImage transmits the hotspot coordinates in the x/y fields of the
 692  * rfbFramebufferUpdateRectHeader, width and height of the image are in the
 693  * header's width and height fields.
 694  * Move transmits the pointer coordinates in the w/h fields of the
 695  * header, x/y are always 0.
 696  */
 697
 698 typedef struct {
 699   CARD8 imageIndex;
 700   CARD8 buttonMask; /* bits 0-7 are buttons 1-8, 0=up, 1=down */
 701 } rfbSoftCursorMove;
 702
 703 typedef struct {
 704   CARD8 imageIndex;
 705   CARD8 padding;
 706   CARD16 imageLength;
 707   /*
 708    * Followed by an image of the cursor in the client's image format
 709    * with the following RLE mask compression. It begins with CARD8 that
 710    * specifies the number of mask'ed pixels that will be NOT transmitted.
 711    * Then follows a CARD8 that specified by the number of unmask'd pixels
 712    * that will be transmitted next. Then a CARD8 with the number of mask'd
 713    * pixels and so on.
 714    */
 715 } rfbSoftCursorSetImage;
 716
 717 typedef union {
 718   CARD8 type;
 719   rfbSoftCursorMove move;
 720   rfbSoftCursorSetImage setImage;
 721 } rfbSoftCursorMsg;
 722
 723 #define rfbSoftCursorMaxImages    16
 724 #define rfbSoftCursorSetIconOffset    128
 725
 726 /*-----------------------------------------------------------------------------
 727  * SetColourMapEntries - these messages are only sent if the pixel
 728  * format uses a "colour map" (i.e. trueColour false) and the client has not
 729  * fixed the entire colour map using FixColourMapEntries.  In addition they
 730  * will only start being sent after the client has sent its first
 731  * FramebufferUpdateRequest.  So if the client always tells the server to use
 732  * trueColour then it never needs to process this type of message.
 733  */
 734
 735 typedef struct {
 736     CARD8 type;                 /* always rfbSetColourMapEntries */
 737     CARD8 pad;
 738     CARD16 firstColour;
 739     CARD16 nColours;
 740
 741     /* Followed by nColours * 3 * CARD16
 742        r1, g1, b1, r2, g2, b2, r3, g3, b3, ..., rn, bn, gn */
 743
 744 } rfbSetColourMapEntriesMsg;
 745
 746 #define sz_rfbSetColourMapEntriesMsg 6
 747
 748
 749
 750 /*-----------------------------------------------------------------------------
 751  * Bell - ring a bell on the client if it has one.
 752  */
 753
 754 typedef struct {
 755     CARD8 type;                 /* always rfbBell */
 756 } rfbBellMsg;
 757
 758 #define sz_rfbBellMsg 1
 759
 760
 761
 762 /*-----------------------------------------------------------------------------
 763  * ServerCutText - the server has new text in its cut buffer.
 764  */
 765
 766 typedef struct {
 767     CARD8 type;                 /* always rfbServerCutText */
 768     CARD8 pad1;
 769     CARD16 pad2;
 770     CARD32 length;
 771     /* followed by char text[length] */
 772 } rfbServerCutTextMsg;
 773
 774 #define sz_rfbServerCutTextMsg 8
 775
 776
 777 /*-----------------------------------------------------------------------------
 778  * Union of all server->client messages.
 779  */
 780
 781 typedef union {
 782     CARD8 type;
 783     rfbFramebufferUpdateMsg fu;
 784     rfbSetColourMapEntriesMsg scme;
 785     rfbBellMsg b;
 786     rfbServerCutTextMsg sct;
 787 } rfbServerToClientMsg;
 788
 789
 790
 791 /*****************************************************************************
 792  *
 793  * Message definitions (client -> server)
 794  *
 795  *****************************************************************************/
 796
 797
 798 /*-----------------------------------------------------------------------------
 799  * SetPixelFormat - tell the RFB server the format in which the client wants
 800  * pixels sent.
 801  */
 802
 803 typedef struct {
 804     CARD8 type;                 /* always rfbSetPixelFormat */
 805     CARD8 pad1;
 806     CARD16 pad2;
 807     rfbPixelFormat format;
 808 } rfbSetPixelFormatMsg;
 809
 810 #define sz_rfbSetPixelFormatMsg (sz_rfbPixelFormat + 4)
 811
 812
 813 /*-----------------------------------------------------------------------------
 814  * FixColourMapEntries - when the pixel format uses a "colour map", fix
 815  * read-only colour map entries.
 816  *
 817  *    ***************** NOT CURRENTLY SUPPORTED *****************
 818  */
 819
 820 typedef struct {
 821     CARD8 type;                 /* always rfbFixColourMapEntries */
 822     CARD8 pad;
 823     CARD16 firstColour;
 824     CARD16 nColours;
 825
 826     /* Followed by nColours * 3 * CARD16
 827        r1, g1, b1, r2, g2, b2, r3, g3, b3, ..., rn, bn, gn */
 828
 829 } rfbFixColourMapEntriesMsg;
 830
 831 #define sz_rfbFixColourMapEntriesMsg 6
 832
 833
 834 /*-----------------------------------------------------------------------------
 835  * SetEncodings - tell the RFB server which encoding types we accept.  Put them
 836  * in order of preference, if we have any.  We may always receive raw
 837  * encoding, even if we don't specify it here.
 838  */
 839
 840 typedef struct {
 841     CARD8 type;                 /* always rfbSetEncodings */
 842     CARD8 pad;
 843     CARD16 nEncodings;
 844     /* followed by nEncodings * CARD32 encoding types */
 845 } rfbSetEncodingsMsg;
 846
 847 #define sz_rfbSetEncodingsMsg 4
 848
 849
 850 /*-----------------------------------------------------------------------------
 851  * FramebufferUpdateRequest - request for a framebuffer update.  If incremental
 852  * is true then the client just wants the changes since the last update.  If
 853  * false then it wants the whole of the specified rectangle.
 854  */
 855
 856 typedef struct {
 857     CARD8 type;                 /* always rfbFramebufferUpdateRequest */
 858     CARD8 incremental;
 859     CARD16 x;
 860     CARD16 y;
 861     CARD16 w;
 862     CARD16 h;
 863 } rfbFramebufferUpdateRequestMsg;
 864
 865 #define sz_rfbFramebufferUpdateRequestMsg 10
 866
 867
 868 /*-----------------------------------------------------------------------------
 869  * KeyEvent - key press or release
 870  *
 871  * Keys are specified using the "keysym" values defined by the X Window System.
 872  * For most ordinary keys, the keysym is the same as the corresponding ASCII
 873  * value.  Other common keys are:
 874  *
 875  * BackSpace            0xff08
 876  * Tab                  0xff09
 877  * Return or Enter      0xff0d
 878  * Escape               0xff1b
 879  * Insert               0xff63
 880  * Delete               0xffff
 881  * Home                 0xff50
 882  * End                  0xff57
 883  * Page Up              0xff55
 884  * Page Down            0xff56
 885  * Left                 0xff51
 886  * Up                   0xff52
 887  * Right                0xff53
 888  * Down                 0xff54
 889  * F1                   0xffbe
 890  * F2                   0xffbf
 891  * ...                  ...
 892  * F12                  0xffc9
 893  * Shift                0xffe1
 894  * Control              0xffe3
 895  * Meta                 0xffe7
 896  * Alt                  0xffe9
 897  */
 898
 899 typedef struct {
 900     CARD8 type;                 /* always rfbKeyEvent */
 901     CARD8 down;                 /* true if down (press), false if up */
 902     CARD16 pad;
 903     CARD32 key;                 /* key is specified as an X keysym */
 904 } rfbKeyEventMsg;
 905
 906 #define sz_rfbKeyEventMsg 8
 907
 908
 909 /*-----------------------------------------------------------------------------
 910  * PointerEvent - mouse/pen move and/or button press.
 911  */
 912
 913 typedef struct {
 914     CARD8 type;                 /* always rfbPointerEvent */
 915     CARD8 buttonMask;           /* bits 0-7 are buttons 1-8, 0=up, 1=down */
 916     CARD16 x;
 917     CARD16 y;
 918 } rfbPointerEventMsg;
 919
 920 #define rfbButton1Mask 1
 921 #define rfbButton2Mask 2
 922 #define rfbButton3Mask 4
 923
 924 #define sz_rfbPointerEventMsg 6
 925
 926
 927
 928 /*-----------------------------------------------------------------------------
 929  * ClientCutText - the client has new text in its cut buffer.
 930  */
 931
 932 typedef struct {
 933     CARD8 type;                 /* always rfbClientCutText */
 934     CARD8 pad1;
 935     CARD16 pad2;
 936     CARD32 length;
 937     /* followed by char text[length] */
 938 } rfbClientCutTextMsg;
 939
 940 #define sz_rfbClientCutTextMsg 8
 941
 942
 943
 944 /*-----------------------------------------------------------------------------
 945  * Union of all client->server messages.
 946  */
 947
 948 typedef union {
 949     CARD8 type;
 950     rfbSetPixelFormatMsg spf;
 951     rfbFixColourMapEntriesMsg fcme;
 952     rfbSetEncodingsMsg se;
 953     rfbFramebufferUpdateRequestMsg fur;
 954     rfbKeyEventMsg ke;
 955     rfbPointerEventMsg pe;
 956     rfbClientCutTextMsg cct;
 957 } rfbClientToServerMsg;