5 * Copyright (C) 2005 Rohit Kumar, Johannes E. Schindelin
6 * Copyright (C) 2000-2002 Constantin Kaplinsky. All Rights Reserved.
7 * Copyright (C) 2000 Tridia Corporation. All Rights Reserved.
8 * Copyright (C) 1999 AT&T Laboratories Cambridge. All Rights Reserved.
10 * This is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; either version 2 of the License, or
13 * (at your option) any later version.
15 * This software is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
20 * You should have received a copy of the GNU General Public License
21 * along with this software; if not, write to the Free Software
22 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
27 * rfbproto.h - header file for the RFB protocol version 3.3
29 * Uses types CARD<n> for an n-bit unsigned integer, INT<n> for an n-bit signed
30 * integer (for n = 8, 16 and 32).
32 * All multiple byte integers are in big endian (network) order (most
33 * significant byte first). Unless noted otherwise there is no special
34 * alignment of protocol structures.
37 * Once the initial handshaking is done, all messages start with a type byte,
38 * (usually) followed by message-specific data. The order of definitions in
39 * this file is as follows:
41 * (1) Structures used in several types of message.
42 * (2) Structures used in the initial handshaking.
45 * (5) For each message type, the form of the data following the type byte.
46 * Sometimes this is defined by a single structure but the more complex
47 * messages have to be explained by comments.
51 #if defined(WIN32) && !defined(__MINGW32__)
52 #define LIBVNCSERVER_WORDS_BIGENDIAN
54 #include <sys/timeb.h>
59 #include <rfb/rfbconfig.h>
60 #include <rfb/rfbint.h>
63 #ifdef LIBVNCSERVER_HAVE_LIBZ
72 #if !defined(WIN32) || defined(__MINGW32__)
73 #define max(a,b) (((a)>(b))?(a):(b))
74 #ifdef LIBVNCSERVER_HAVE_SYS_TIME_H
77 #ifdef LIBVNCSERVER_HAVE_NETINET_IN_H
78 #include <netinet/in.h>
81 typedef int8_t rfbBool;
88 typedef uint32_t rfbKeySym;
89 typedef uint32_t rfbPixel;
91 #ifdef LIBVNCSERVER_NEED_INADDR_T
92 typedef uint32_t in_addr_t;
96 #define INADDR_NONE ((in_addr_t) 0xffffffff)
99 #define MAX_ENCODINGS 20
101 /*****************************************************************************
103 * Structures used in several messages
105 *****************************************************************************/
107 /*-----------------------------------------------------------------------------
108 * Structure used to specify a rectangle. This structure is a multiple of 4
109 * bytes so that it can be interspersed with 32-bit pixel data without
110 * affecting alignment.
120 #define sz_rfbRectangle 8
123 /*-----------------------------------------------------------------------------
124 * Structure used to specify pixel format.
129 uint8_t bitsPerPixel; /* 8,16,32 only */
131 uint8_t depth; /* 8 to 32 */
133 uint8_t bigEndian; /* True if multi-byte pixels are interpreted
134 as big endian, or if single-bit-per-pixel
135 has most significant bit of the byte
136 corresponding to first (leftmost) pixel. Of
137 course this is meaningless for 8 bits/pix */
139 uint8_t trueColour; /* If false then we need a "colour map" to
140 convert pixels to RGB. If true, xxxMax and
141 xxxShift specify bits used for red, green
144 /* the following fields are only meaningful if trueColour is true */
146 uint16_t redMax; /* maximum red value (= 2^n - 1 where n is the
147 number of bits used for red). Note this
148 value is always in big endian order. */
150 uint16_t greenMax; /* similar for green */
152 uint16_t blueMax; /* and blue */
154 uint8_t redShift; /* number of shifts needed to get the red
155 value in a pixel to the least significant
156 bit. To find the red value from a given
157 pixel, do the following:
158 1) Swap pixel value according to bigEndian
159 (e.g. if bigEndian is false and host byte
160 order is big endian, then swap).
161 2) Shift right by redShift.
162 3) AND with redMax (in host byte order).
163 4) You now have the red value between 0 and
166 uint8_t greenShift; /* similar for green */
168 uint8_t blueShift; /* and blue */
175 #define sz_rfbPixelFormat 16
177 /* UltraVNC: Color settings values */
178 #define rfbPFFullColors 0
179 #define rfbPF256Colors 1
180 #define rfbPF64Colors 2
181 #define rfbPF8Colors 3
182 #define rfbPF8GreyColors 4
183 #define rfbPF4GreyColors 5
184 #define rfbPF2GreyColors 6
187 /*****************************************************************************
189 * Initial handshaking messages
191 *****************************************************************************/
193 /*-----------------------------------------------------------------------------
196 * The server always sends 12 bytes to start which identifies the latest RFB
197 * protocol version number which it supports. These bytes are interpreted
198 * as a string of 12 ASCII characters in the format "RFB xxx.yyy\n" where
199 * xxx and yyy are the major and minor version numbers (for version 3.3
200 * this is "RFB 003.003\n").
202 * The client then replies with a similar 12-byte message giving the version
203 * number of the protocol which should actually be used (which may be different
204 * to that quoted by the server).
206 * It is intended that both clients and servers may provide some level of
207 * backwards compatibility by this mechanism. Servers in particular should
208 * attempt to provide backwards compatibility, and even forwards compatibility
209 * to some extent. For example if a client demands version 3.1 of the
210 * protocol, a 3.0 server can probably assume that by ignoring requests for
211 * encoding types it doesn't understand, everything will still work OK. This
212 * will probably not be the case for changes in the major version number.
214 * The format string below can be used in sprintf or sscanf to generate or
215 * decode the version string respectively.
218 #define rfbProtocolVersionFormat "RFB %03d.%03d\n"
219 #define rfbProtocolMajorVersion 3
220 #define rfbProtocolMinorVersion 8
221 /* UltraVNC Viewer examines rfbProtocolMinorVersion number (4, and 6)
222 * to identify if the server supports File Transfer
225 typedef char rfbProtocolVersionMsg[13]; /* allow extra byte for null */
227 #define sz_rfbProtocolVersionMsg 12
230 * Negotiation of the security type (protocol version 3.7)
232 * Once the protocol version has been decided, the server either sends a list
233 * of supported security types, or informs the client about an error (when the
234 * number of security types is 0). Security type rfbSecTypeTight is used to
235 * enable TightVNC-specific protocol extensions. The value rfbSecTypeVncAuth
236 * stands for classic VNC authentication.
238 * The client selects a particular security type from the list provided by the
242 #define rfbSecTypeInvalid 0
243 #define rfbSecTypeNone 1
244 #define rfbSecTypeVncAuth 2
247 /*-----------------------------------------------------------------------------
250 * Once the protocol version has been decided, the server then sends a 32-bit
251 * word indicating whether any authentication is needed on the connection.
252 * The value of this word determines the authentication scheme in use. For
253 * version 3.0 of the protocol this may have one of the following values:
256 #define rfbConnFailed 0
269 * rfbConnFailed: For some reason the connection failed (e.g. the server
270 * cannot support the desired protocol version). This is
271 * followed by a string describing the reason (where a
272 * string is specified as a 32-bit length followed by that
273 * many ASCII characters).
275 * rfbNoAuth: No authentication is needed.
277 * rfbVncAuth: The VNC authentication scheme is to be used. A 16-byte
278 * challenge follows, which the client encrypts as
279 * appropriate using the password and sends the resulting
280 * 16-byte response. If the response is correct, the
281 * server sends the 32-bit word rfbVncAuthOK. If a simple
282 * failure happens, the server sends rfbVncAuthFailed and
283 * closes the connection. If the server decides that too
284 * many failures have occurred, it sends rfbVncAuthTooMany
285 * and closes the connection. In the latter case, the
286 * server should not allow an immediate reconnection by
290 #define rfbVncAuthOK 0
291 #define rfbVncAuthFailed 1
292 #define rfbVncAuthTooMany 2
295 /*-----------------------------------------------------------------------------
296 * Client Initialisation Message
298 * Once the client and server are sure that they're happy to talk to one
299 * another, the client sends an initialisation message. At present this
300 * message only consists of a boolean indicating whether the server should try
301 * to share the desktop by leaving other clients connected, or give exclusive
302 * access to this client by disconnecting all other clients.
309 #define sz_rfbClientInitMsg 1
312 /*-----------------------------------------------------------------------------
313 * Server Initialisation Message
315 * After the client initialisation message, the server sends one of its own.
316 * This tells the client the width and height of the server's framebuffer,
317 * its pixel format and the name associated with the desktop.
321 uint16_t framebufferWidth;
322 uint16_t framebufferHeight;
323 rfbPixelFormat format; /* the server's preferred pixel format */
325 /* followed by char name[nameLength] */
328 #define sz_rfbServerInitMsg (8 + sz_rfbPixelFormat)
332 * Following the server initialisation message it's up to the client to send
333 * whichever protocol messages it wants. Typically it will send a
334 * SetPixelFormat message and a SetEncodings message, followed by a
335 * FramebufferUpdateRequest. From then on the server will send
336 * FramebufferUpdate messages in response to the client's
337 * FramebufferUpdateRequest messages. The client should send
338 * FramebufferUpdateRequest messages with incremental set to true when it has
339 * finished processing one FramebufferUpdate and is ready to process another.
340 * With a fast client, the rate at which FramebufferUpdateRequests are sent
341 * should be regulated to avoid hogging the network.
346 /*****************************************************************************
350 *****************************************************************************/
352 /* server -> client */
354 #define rfbFramebufferUpdate 0
355 #define rfbSetColourMapEntries 1
357 #define rfbServerCutText 3
359 #define rfbResizeFrameBuffer 4
360 #define rfbKeyFrameUpdate 5
361 #define rfbPalmVNCReSizeFrameBuffer 0xF
363 /* client -> server */
365 #define rfbSetPixelFormat 0
366 #define rfbFixColourMapEntries 1 /* not currently supported */
367 #define rfbSetEncodings 2
368 #define rfbFramebufferUpdateRequest 3
369 #define rfbKeyEvent 4
370 #define rfbPointerEvent 5
371 #define rfbClientCutText 6
372 /* Modif sf@2002 - actually bidirectionnal */
373 #define rfbFileTransfer 7
375 #define rfbSetScale 8
377 #define rfbSetServerInput 9
380 /* Modif sf@2002 - TextChat - Bidirectionnal */
381 #define rfbTextChat 11
383 #define rfbKeyFrameRequest 12
384 /* PalmVNC 1.4 & 2.0 SetScale Factor message */
385 #define rfbPalmVNCSetScaleFactor 0xF
390 /*****************************************************************************
394 *****************************************************************************/
396 #define rfbEncodingRaw 0
397 #define rfbEncodingCopyRect 1
398 #define rfbEncodingRRE 2
399 #define rfbEncodingCoRRE 4
400 #define rfbEncodingHextile 5
401 #define rfbEncodingZlib 6
402 #define rfbEncodingTight 7
403 #define rfbEncodingZlibHex 8
404 #define rfbEncodingUltra 9
405 #define rfbEncodingZRLE 16
406 #define rfbEncodingZYWRLE 17
408 /* Cache & XOR-Zlib - rdv@2002 */
409 #define rfbEncodingCache 0xFFFF0000
410 #define rfbEncodingCacheEnable 0xFFFF0001
411 #define rfbEncodingXOR_Zlib 0xFFFF0002
412 #define rfbEncodingXORMonoColor_Zlib 0xFFFF0003
413 #define rfbEncodingXORMultiColor_Zlib 0xFFFF0004
414 #define rfbEncodingSolidColor 0xFFFF0005
415 #define rfbEncodingXOREnable 0xFFFF0006
416 #define rfbEncodingCacheZip 0xFFFF0007
417 #define rfbEncodingSolMonoZip 0xFFFF0008
418 #define rfbEncodingUltraZip 0xFFFF0009
421 * Special encoding numbers:
422 * 0xFFFFFF00 .. 0xFFFFFF0F -- encoding-specific compression levels;
423 * 0xFFFFFF10 .. 0xFFFFFF1F -- mouse cursor shape data;
424 * 0xFFFFFF20 .. 0xFFFFFF2F -- various protocol extensions;
425 * 0xFFFFFF30 .. 0xFFFFFFDF -- not allocated yet;
426 * 0xFFFFFFE0 .. 0xFFFFFFEF -- quality level for JPEG compressor;
427 * 0xFFFFFFF0 .. 0xFFFFFFFF -- cross-encoding compression levels.
430 #define rfbEncodingCompressLevel0 0xFFFFFF00
431 #define rfbEncodingCompressLevel1 0xFFFFFF01
432 #define rfbEncodingCompressLevel2 0xFFFFFF02
433 #define rfbEncodingCompressLevel3 0xFFFFFF03
434 #define rfbEncodingCompressLevel4 0xFFFFFF04
435 #define rfbEncodingCompressLevel5 0xFFFFFF05
436 #define rfbEncodingCompressLevel6 0xFFFFFF06
437 #define rfbEncodingCompressLevel7 0xFFFFFF07
438 #define rfbEncodingCompressLevel8 0xFFFFFF08
439 #define rfbEncodingCompressLevel9 0xFFFFFF09
441 #define rfbEncodingXCursor 0xFFFFFF10
442 #define rfbEncodingRichCursor 0xFFFFFF11
443 #define rfbEncodingPointerPos 0xFFFFFF18
445 #define rfbEncodingLastRect 0xFFFFFF20
446 #define rfbEncodingNewFBSize 0xFFFFFF21
448 #define rfbEncodingQualityLevel0 0xFFFFFFE0
449 #define rfbEncodingQualityLevel1 0xFFFFFFE1
450 #define rfbEncodingQualityLevel2 0xFFFFFFE2
451 #define rfbEncodingQualityLevel3 0xFFFFFFE3
452 #define rfbEncodingQualityLevel4 0xFFFFFFE4
453 #define rfbEncodingQualityLevel5 0xFFFFFFE5
454 #define rfbEncodingQualityLevel6 0xFFFFFFE6
455 #define rfbEncodingQualityLevel7 0xFFFFFFE7
456 #define rfbEncodingQualityLevel8 0xFFFFFFE8
457 #define rfbEncodingQualityLevel9 0xFFFFFFE9
460 /* LibVNCServer additions. We claim 0xFFFE0000 - 0xFFFE00FF */
461 #define rfbEncodingKeyboardLedState 0xFFFE0000
462 #define rfbEncodingSupportedMessages 0xFFFE0001
463 #define rfbEncodingSupportedEncodings 0xFFFE0002
464 #define rfbEncodingServerIdentity 0xFFFE0003
467 /*****************************************************************************
469 * Server -> client message definitions
471 *****************************************************************************/
474 /*-----------------------------------------------------------------------------
475 * FramebufferUpdate - a block of rectangles to be copied to the framebuffer.
477 * This message consists of a header giving the number of rectangles of pixel
478 * data followed by the rectangles themselves. The header is padded so that
479 * together with the type byte it is an exact multiple of 4 bytes (to help
480 * with alignment of 32-bit pixels):
484 uint8_t type; /* always rfbFramebufferUpdate */
487 /* followed by nRects rectangles */
488 } rfbFramebufferUpdateMsg;
490 #define sz_rfbFramebufferUpdateMsg 4
492 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
493 * KeyFrameUpdate - Acknowledgment of a key frame request, it tells the client
494 * that the next update received will be a key frame.
499 } rfbKeyFrameUpdateMsg;
501 #define sz_rfbKeyFrameUpdateMsg 1
505 * Each rectangle of pixel data consists of a header describing the position
506 * and size of the rectangle and a type word describing the encoding of the
507 * pixel data, followed finally by the pixel data. Note that if the client has
508 * not sent a SetEncodings message then it will only receive raw pixel data.
509 * Also note again that this structure is a multiple of 4 bytes.
514 uint32_t encoding; /* one of the encoding types rfbEncoding... */
515 } rfbFramebufferUpdateRectHeader;
517 #define sz_rfbFramebufferUpdateRectHeader (sz_rfbRectangle + 4)
519 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
520 * Supported Messages Encoding. This encoding does not contain any pixel data.
521 * Instead, it contains 2 sets of bitflags. These bitflags indicate what messages
522 * are supported by the server.
523 * rect->w contains byte count
527 uint8_t client2server[32]; /* maximum of 256 message types (256/8)=32 */
528 uint8_t server2client[32]; /* maximum of 256 message types (256/8)=32 */
529 } rfbSupportedMessages;
531 #define sz_rfbSupportedMessages 64
533 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
534 * Supported Encodings Encoding. This encoding does not contain any pixel data.
535 * Instead, it contains a list of (uint32_t) Encodings supported by this server.
536 * rect->w contains byte count
537 * rect->h contains encoding count
540 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
541 * Server Identity Encoding. This encoding does not contain any pixel data.
542 * Instead, it contains a text string containing information about the server.
543 * ie: "x11vnc: 0.8.1 lastmod: 2006-04-25 (libvncserver 0.9pre)\0"
544 * rect->w contains byte count
548 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
549 * Raw Encoding. Pixels are sent in top-to-bottom scanline order,
550 * left-to-right within a scanline with no padding in between.
553 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
554 * KeyboardLedState Encoding. The X coordinate contains the Locked Modifiers
555 * so that a remote troubleshooter can identify that the users 'Caps Lock'
556 * is set... (It helps a *lot* when the users are untrained)
558 #define rfbKeyboardMaskShift 1
559 #define rfbKeyboardMaskCapsLock 2
560 #define rfbKeyboardMaskControl 4
561 #define rfbKeyboardMaskAlt 8
562 #define rfbKeyboardMaskMeta 16
563 #define rfbKeyboardMaskSuper 32
564 #define rfbKeyboardMaskHyper 64
565 #define rfbKeyboardMaskNumLock 128
566 #define rfbKeyboardMaskScrollLock 256
567 #define rfbKeyboardMaskAltGraph 512
569 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
570 * CopyRect Encoding. The pixels are specified simply by the x and y position
571 * of the source rectangle.
579 #define sz_rfbCopyRect 4
582 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
583 * RRE - Rise-and-Run-length Encoding. We have an rfbRREHeader structure
584 * giving the number of subrectangles following. Finally the data follows in
585 * the form [<bgpixel><subrect><subrect>...] where each <subrect> is
586 * [<pixel><rfbRectangle>].
593 #define sz_rfbRREHeader 4
596 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
597 * CoRRE - Compact RRE Encoding. We have an rfbRREHeader structure giving
598 * the number of subrectangles following. Finally the data follows in the form
599 * [<bgpixel><subrect><subrect>...] where each <subrect> is
600 * [<pixel><rfbCoRRERectangle>]. This means that
601 * the whole rectangle must be at most 255x255 pixels.
611 #define sz_rfbCoRRERectangle 4
614 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
615 * Hextile Encoding. The rectangle is divided up into "tiles" of 16x16 pixels,
616 * starting at the top left going in left-to-right, top-to-bottom order. If
617 * the width of the rectangle is not an exact multiple of 16 then the width of
618 * the last tile in each row will be correspondingly smaller. Similarly if the
619 * height is not an exact multiple of 16 then the height of each tile in the
620 * final row will also be smaller. Each tile begins with a "subencoding" type
621 * byte, which is a mask made up of a number of bits. If the Raw bit is set
622 * then the other bits are irrelevant; w*h pixel values follow (where w and h
623 * are the width and height of the tile). Otherwise the tile is encoded in a
624 * similar way to RRE, except that the position and size of each subrectangle
625 * can be specified in just two bytes. The other bits in the mask are as
628 * BackgroundSpecified - if set, a pixel value follows which specifies
629 * the background colour for this tile. The first non-raw tile in a
630 * rectangle must have this bit set. If this bit isn't set then the
631 * background is the same as the last tile.
633 * ForegroundSpecified - if set, a pixel value follows which specifies
634 * the foreground colour to be used for all subrectangles in this tile.
635 * If this bit is set then the SubrectsColoured bit must be zero.
637 * AnySubrects - if set, a single byte follows giving the number of
638 * subrectangles following. If not set, there are no subrectangles (i.e.
639 * the whole tile is just solid background colour).
641 * SubrectsColoured - if set then each subrectangle is preceded by a pixel
642 * value giving the colour of that subrectangle. If not set, all
643 * subrectangles are the same colour, the foreground colour; if the
644 * ForegroundSpecified bit wasn't set then the foreground is the same as
647 * The position and size of each subrectangle is specified in two bytes. The
648 * Pack macros below can be used to generate the two bytes from x, y, w, h,
649 * and the Extract macros can be used to extract the x, y, w, h values from
653 #define rfbHextileRaw (1 << 0)
654 #define rfbHextileBackgroundSpecified (1 << 1)
655 #define rfbHextileForegroundSpecified (1 << 2)
656 #define rfbHextileAnySubrects (1 << 3)
657 #define rfbHextileSubrectsColoured (1 << 4)
659 #define rfbHextilePackXY(x,y) (((x) << 4) | (y))
660 #define rfbHextilePackWH(w,h) ((((w)-1) << 4) | ((h)-1))
661 #define rfbHextileExtractX(byte) ((byte) >> 4)
662 #define rfbHextileExtractY(byte) ((byte) & 0xf)
663 #define rfbHextileExtractW(byte) (((byte) >> 4) + 1)
664 #define rfbHextileExtractH(byte) (((byte) & 0xf) + 1)
666 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
667 * zlib - zlib compressed Encoding. We have an rfbZlibHeader structure
668 * giving the number of bytes following. Finally the data follows is
669 * zlib compressed version of the raw pixel data as negotiated.
670 * (NOTE: also used by Ultra Encoding)
677 #define sz_rfbZlibHeader 4
679 #ifdef LIBVNCSERVER_HAVE_LIBZ
681 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
684 *-- The first byte of each Tight-encoded rectangle is a "compression control
685 * byte". Its format is as follows (bit 0 is the least significant one):
687 * bit 0: if 1, then compression stream 0 should be reset;
688 * bit 1: if 1, then compression stream 1 should be reset;
689 * bit 2: if 1, then compression stream 2 should be reset;
690 * bit 3: if 1, then compression stream 3 should be reset;
691 * bits 7-4: if 1000 (0x08), then the compression type is "fill",
692 * if 1001 (0x09), then the compression type is "jpeg",
693 * if 0xxx, then the compression type is "basic",
694 * values greater than 1001 are not valid.
696 * If the compression type is "basic", then bits 6..4 of the
697 * compression control byte (those xxx in 0xxx) specify the following:
699 * bits 5-4: decimal representation is the index of a particular zlib
700 * stream which should be used for decompressing the data;
701 * bit 6: if 1, then a "filter id" byte is following this byte.
703 *-- The data that follows after the compression control byte described
704 * above depends on the compression type ("fill", "jpeg" or "basic").
706 *-- If the compression type is "fill", then the only pixel value follows, in
707 * client pixel format (see NOTE 1). This value applies to all pixels of the
710 *-- If the compression type is "jpeg", the following data stream looks like
713 * 1..3 bytes: data size (N) in compact representation;
714 * N bytes: JPEG image.
716 * Data size is compactly represented in one, two or three bytes, according
717 * to the following scheme:
719 * 0xxxxxxx (for values 0..127)
720 * 1xxxxxxx 0yyyyyyy (for values 128..16383)
721 * 1xxxxxxx 1yyyyyyy zzzzzzzz (for values 16384..4194303)
723 * Here each character denotes one bit, xxxxxxx are the least significant 7
724 * bits of the value (bits 0-6), yyyyyyy are bits 7-13, and zzzzzzzz are the
725 * most significant 8 bits (bits 14-21). For example, decimal value 10000
726 * should be represented as two bytes: binary 10010000 01001110, or
729 *-- If the compression type is "basic" and bit 6 of the compression control
730 * byte was set to 1, then the next (second) byte specifies "filter id" which
731 * tells the decoder what filter type was used by the encoder to pre-process
732 * pixel data before the compression. The "filter id" byte can be one of the
735 * 0: no filter ("copy" filter);
736 * 1: "palette" filter;
737 * 2: "gradient" filter.
739 *-- If bit 6 of the compression control byte is set to 0 (no "filter id"
740 * byte), or if the filter id is 0, then raw pixel values in the client
741 * format (see NOTE 1) will be compressed. See below details on the
744 *-- The "gradient" filter pre-processes pixel data with a simple algorithm
745 * which converts each color component to a difference between a "predicted"
746 * intensity and the actual intensity. Such a technique does not affect
747 * uncompressed data size, but helps to compress photo-like images better.
748 * Pseudo-code for converting intensities to differences is the following:
750 * P[i,j] := V[i-1,j] + V[i,j-1] - V[i-1,j-1];
751 * if (P[i,j] < 0) then P[i,j] := 0;
752 * if (P[i,j] > MAX) then P[i,j] := MAX;
753 * D[i,j] := V[i,j] - P[i,j];
755 * Here V[i,j] is the intensity of a color component for a pixel at
756 * coordinates (i,j). MAX is the maximum value of intensity for a color
759 *-- The "palette" filter converts true-color pixel data to indexed colors
760 * and a palette which can consist of 2..256 colors. If the number of colors
761 * is 2, then each pixel is encoded in 1 bit, otherwise 8 bits is used to
762 * encode one pixel. 1-bit encoding is performed such way that the most
763 * significant bits correspond to the leftmost pixels, and each raw of pixels
764 * is aligned to the byte boundary. When "palette" filter is used, the
765 * palette is sent before the pixel data. The palette begins with an unsigned
766 * byte which value is the number of colors in the palette minus 1 (i.e. 1
767 * means 2 colors, 255 means 256 colors in the palette). Then follows the
768 * palette itself which consist of pixel values in client pixel format (see
771 *-- The pixel data is compressed using the zlib library. But if the data
772 * size after applying the filter but before the compression is less then 12,
773 * then the data is sent as is, uncompressed. Four separate zlib streams
774 * (0..3) can be used and the decoder should read the actual stream id from
775 * the compression control byte (see NOTE 2).
777 * If the compression is not used, then the pixel data is sent as is,
778 * otherwise the data stream looks like this:
780 * 1..3 bytes: data size (N) in compact representation;
781 * N bytes: zlib-compressed data.
783 * Data size is compactly represented in one, two or three bytes, just like
784 * in the "jpeg" compression method (see above).
786 *-- NOTE 1. If the color depth is 24, and all three color components are
787 * 8-bit wide, then one pixel in Tight encoding is always represented by
788 * three bytes, where the first byte is red component, the second byte is
789 * green component, and the third byte is blue component of the pixel color
790 * value. This applies to colors in palettes as well.
792 *-- NOTE 2. The decoder must reset compression streams' states before
793 * decoding the rectangle, if some of bits 0,1,2,3 in the compression control
794 * byte are set to 1. Note that the decoder must reset zlib streams even if
795 * the compression type is "fill" or "jpeg".
797 *-- NOTE 3. The "gradient" filter and "jpeg" compression may be used only
798 * when bits-per-pixel value is either 16 or 32, not 8.
800 *-- NOTE 4. The width of any Tight-encoded rectangle cannot exceed 2048
801 * pixels. If a rectangle is wider, it must be split into several rectangles
802 * and each one should be encoded separately.
806 #define rfbTightExplicitFilter 0x04
807 #define rfbTightFill 0x08
808 #define rfbTightJpeg 0x09
809 #define rfbTightMaxSubencoding 0x09
811 /* Filters to improve compression efficiency */
812 #define rfbTightFilterCopy 0x00
813 #define rfbTightFilterPalette 0x01
814 #define rfbTightFilterGradient 0x02
818 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
819 * XCursor encoding. This is a special encoding used to transmit X-style
820 * cursor shapes from server to clients. Note that for this encoding,
821 * coordinates in rfbFramebufferUpdateRectHeader structure hold hotspot
822 * position (r.x, r.y) and cursor size (r.w, r.h). If (w * h != 0), two RGB
823 * samples are sent after header in the rfbXCursorColors structure. They
824 * denote foreground and background colors of the cursor. If a client
825 * supports only black-and-white cursors, it should ignore these colors and
826 * assume that foreground is black and background is white. Next, two bitmaps
827 * (1 bits per pixel) follow: first one with actual data (value 0 denotes
828 * background color, value 1 denotes foreground color), second one with
829 * transparency data (bits with zero value mean that these pixels are
830 * transparent). Both bitmaps represent cursor data in a byte stream, from
831 * left to right, from top to bottom, and each row is byte-aligned. Most
832 * significant bits correspond to leftmost pixels. The number of bytes in
833 * each row can be calculated as ((w + 7) / 8). If (w * h == 0), cursor
834 * should be hidden (or default local cursor should be set by the client).
846 #define sz_rfbXCursorColors 6
849 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
850 * RichCursor encoding. This is a special encoding used to transmit cursor
851 * shapes from server to clients. It is similar to the XCursor encoding but
852 * uses client pixel format instead of two RGB colors to represent cursor
853 * image. For this encoding, coordinates in rfbFramebufferUpdateRectHeader
854 * structure hold hotspot position (r.x, r.y) and cursor size (r.w, r.h).
855 * After header, two pixmaps follow: first one with cursor image in current
856 * client pixel format (like in raw encoding), second with transparency data
857 * (1 bit per pixel, exactly the same format as used for transparency bitmap
858 * in the XCursor encoding). If (w * h == 0), cursor should be hidden (or
859 * default local cursor should be set by the client).
863 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
864 * ZRLE - encoding combining Zlib compression, tiling, palettisation and
865 * run-length encoding.
872 #define sz_rfbZRLEHeader 4
874 #define rfbZRLETileWidth 64
875 #define rfbZRLETileHeight 64
878 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
879 * ZLIBHEX - zlib compressed Hextile Encoding. Essentially, this is the
880 * hextile encoding with zlib compression on the tiles that can not be
881 * efficiently encoded with one of the other hextile subencodings. The
882 * new zlib subencoding uses two bytes to specify the length of the
883 * compressed tile and then the compressed data follows. As with the
884 * raw sub-encoding, the zlib subencoding invalidates the other
885 * values, if they are also set.
888 #define rfbHextileZlibRaw (1 << 5)
889 #define rfbHextileZlibHex (1 << 6)
890 #define rfbHextileZlibMono (1 << 7)
893 /*-----------------------------------------------------------------------------
894 * SetColourMapEntries - these messages are only sent if the pixel
895 * format uses a "colour map" (i.e. trueColour false) and the client has not
896 * fixed the entire colour map using FixColourMapEntries. In addition they
897 * will only start being sent after the client has sent its first
898 * FramebufferUpdateRequest. So if the client always tells the server to use
899 * trueColour then it never needs to process this type of message.
903 uint8_t type; /* always rfbSetColourMapEntries */
905 uint16_t firstColour;
908 /* Followed by nColours * 3 * uint16_t
909 r1, g1, b1, r2, g2, b2, r3, g3, b3, ..., rn, bn, gn */
911 } rfbSetColourMapEntriesMsg;
913 #define sz_rfbSetColourMapEntriesMsg 6
917 /*-----------------------------------------------------------------------------
918 * Bell - ring a bell on the client if it has one.
922 uint8_t type; /* always rfbBell */
925 #define sz_rfbBellMsg 1
929 /*-----------------------------------------------------------------------------
930 * ServerCutText - the server has new text in its cut buffer.
934 uint8_t type; /* always rfbServerCutText */
938 /* followed by char text[length] */
939 } rfbServerCutTextMsg;
941 #define sz_rfbServerCutTextMsg 8
944 /*-----------------------------------------------------------------------------
946 * FileTransferMsg - The client sends FileTransfer message.
947 * Bidirectional message - Files can be sent from client to server & vice versa
950 typedef struct _rfbFileTransferMsg {
951 uint8_t type; /* always rfbFileTransfer */
952 uint8_t contentType; /* See defines below */
953 uint8_t contentParam;/* Other possible content classification (Dir or File name, etc..) */
954 uint8_t pad; /* It appears that UltraVNC *forgot* to Swap16IfLE(contentParam) */
955 uint32_t size; /* FileSize or packet index or error or other */
956 /* uint32_t sizeH; Additional 32Bits params to handle big values. Only for V2 (we want backward compatibility between all V1 versions) */
958 /* followed by data char text[length] */
959 } rfbFileTransferMsg;
961 #define sz_rfbFileTransferMsg 12
963 #define rfbFileTransferVersion 2 /* v1 is the old FT version ( <= 1.0.0 RC18 versions) */
965 /* FileTransfer Content types and Params defines */
966 #define rfbDirContentRequest 1 /* Client asks for the content of a given Server directory */
967 #define rfbDirPacket 2 /* Full directory name or full file name. */
968 /* Null content means end of Directory */
969 #define rfbFileTransferRequest 3 /* Client asks the server for the transfer of a given file */
970 #define rfbFileHeader 4 /* First packet of a file transfer, containing file's features */
971 #define rfbFilePacket 5 /* One chunk of the file */
972 #define rfbEndOfFile 6 /* End of file transfer (the file has been received or error) */
973 #define rfbAbortFileTransfer 7 /* The file transfer must be aborted, whatever the state */
974 #define rfbFileTransferOffer 8 /* The client offers to send a file to the server */
975 #define rfbFileAcceptHeader 9 /* The server accepts or rejects the file */
976 #define rfbCommand 10 /* The Client sends a simple command (File Delete, Dir create etc...) */
977 #define rfbCommandReturn 11 /* The Client receives the server's answer about a simple command */
978 #define rfbFileChecksums 12 /* The zipped checksums of the destination file (Delta Transfer) */
979 #define rfbFileTransferAccess 14 /* Request FileTransfer authorization */
981 /* rfbDirContentRequest client Request - content params */
982 #define rfbRDirContent 1 /* Request a Server Directory contents */
983 #define rfbRDrivesList 2 /* Request the server's drives list */
984 #define rfbRDirRecursiveList 3 /* Request a server directory content recursive sorted list */
985 #define rfbRDirRecursiveSize 4 /* Request a server directory content recursive size */
987 /* rfbDirPacket & rfbCommandReturn server Answer - content params */
988 #define rfbADirectory 1 /* Reception of a directory name */
989 #define rfbAFile 2 /* Reception of a file name */
990 #define rfbADrivesList 3 /* Reception of a list of drives */
991 #define rfbADirCreate 4 /* Response to a create dir command */
992 #define rfbADirDelete 5 /* Response to a delete dir command */
993 #define rfbAFileCreate 6 /* Response to a create file command */
994 #define rfbAFileDelete 7 /* Response to a delete file command */
995 #define rfbAFileRename 8 /* Response to a rename file command */
996 #define rfbADirRename 9 /* Response to a rename dir command */
997 #define rfbADirRecursiveListItem 10
998 #define rfbADirRecursiveSize 11
1000 /* rfbCommand Command - content params */
1001 #define rfbCDirCreate 1 /* Request the server to create the given directory */
1002 #define rfbCDirDelete 2 /* Request the server to delete the given directory */
1003 #define rfbCFileCreate 3 /* Request the server to create the given file */
1004 #define rfbCFileDelete 4 /* Request the server to delete the given file */
1005 #define rfbCFileRename 5 /* Request the server to rename the given file */
1006 #define rfbCDirRename 6 /* Request the server to rename the given directory */
1008 /* Errors - content params or "size" field */
1009 #define rfbRErrorUnknownCmd 1 /* Unknown FileTransfer command. */
1010 #define rfbRErrorCmd 0xFFFFFFFF/* Error when a command fails on remote side (ret in "size" field) */
1012 #define sz_rfbBlockSize 8192 /* Size of a File Transfer packet (before compression) */
1013 #define rfbZipDirectoryPrefix "!UVNCDIR-\0" /* Transfered directory are zipped in a file with this prefix. Must end with "-" */
1014 #define sz_rfbZipDirectoryPrefix 9
1015 #define rfbDirPrefix "[ "
1016 #define rfbDirSuffix " ]"
1020 /*-----------------------------------------------------------------------------
1022 * TextChatMsg - Utilized to order the TextChat mode on server or client
1023 * Bidirectional message
1026 typedef struct _rfbTextChatMsg {
1027 uint8_t type; /* always rfbTextChat */
1028 uint8_t pad1; /* Could be used later as an additionnal param */
1029 uint16_t pad2; /* Could be used later as text offset, for instance */
1030 uint32_t length; /* Specific values for Open, close, finished (-1, -2, -3) */
1031 /* followed by char text[length] */
1034 #define sz_rfbTextChatMsg 8
1036 #define rfbTextMaxSize 4096
1037 #define rfbTextChatOpen 0xFFFFFFFF
1038 #define rfbTextChatClose 0xFFFFFFFE
1039 #define rfbTextChatFinished 0xFFFFFFFD
1043 /*-----------------------------------------------------------------------------
1045 * ResizeFrameBuffer - The Client must change the size of its framebuffer
1048 typedef struct _rfbResizeFrameBufferMsg {
1049 uint8_t type; /* always rfbResizeFrameBuffer */
1051 uint16_t framebufferWidth; /* FrameBuffer width */
1052 uint16_t framebufferHeigth; /* FrameBuffer height */
1053 } rfbResizeFrameBufferMsg;
1055 #define sz_rfbResizeFrameBufferMsg 6
1058 /*-----------------------------------------------------------------------------
1059 * Copyright (C) 2001 Harakan Software
1060 * PalmVNC 1.4 & 2.? ResizeFrameBuffer message
1061 * ReSizeFrameBuffer - tell the RFB client to alter its framebuffer, either
1062 * due to a resize of the server desktop or a client-requested scaling factor.
1063 * The pixel format remains unchanged.
1067 uint8_t type; /* always rfbReSizeFrameBuffer */
1069 uint16_t desktop_w; /* Desktop width */
1070 uint16_t desktop_h; /* Desktop height */
1071 uint16_t buffer_w; /* FrameBuffer width */
1072 uint16_t buffer_h; /* Framebuffer height */
1075 } rfbPalmVNCReSizeFrameBufferMsg;
1077 #define sz_rfbPalmVNCReSizeFrameBufferMsg (12)
1082 /*-----------------------------------------------------------------------------
1083 * Union of all server->client messages.
1088 rfbFramebufferUpdateMsg fu;
1089 rfbSetColourMapEntriesMsg scme;
1091 rfbServerCutTextMsg sct;
1092 rfbResizeFrameBufferMsg rsfb;
1093 rfbPalmVNCReSizeFrameBufferMsg prsfb;
1094 rfbFileTransferMsg ft;
1096 } rfbServerToClientMsg;
1100 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1101 * RDV Cache Encoding.
1102 * special is not used at this point, can be used to reset cache or other specials
1103 * just put it to make sure we don't have to change the encoding again.
1110 #define sz_rfbCacheRect 2
1115 /*****************************************************************************
1117 * Message definitions (client -> server)
1119 *****************************************************************************/
1122 /*-----------------------------------------------------------------------------
1123 * SetPixelFormat - tell the RFB server the format in which the client wants
1128 uint8_t type; /* always rfbSetPixelFormat */
1131 rfbPixelFormat format;
1132 } rfbSetPixelFormatMsg;
1134 #define sz_rfbSetPixelFormatMsg (sz_rfbPixelFormat + 4)
1137 /*-----------------------------------------------------------------------------
1138 * FixColourMapEntries - when the pixel format uses a "colour map", fix
1139 * read-only colour map entries.
1141 * ***************** NOT CURRENTLY SUPPORTED *****************
1145 uint8_t type; /* always rfbFixColourMapEntries */
1147 uint16_t firstColour;
1150 /* Followed by nColours * 3 * uint16_t
1151 r1, g1, b1, r2, g2, b2, r3, g3, b3, ..., rn, bn, gn */
1153 } rfbFixColourMapEntriesMsg;
1155 #define sz_rfbFixColourMapEntriesMsg 6
1158 /*-----------------------------------------------------------------------------
1159 * SetEncodings - tell the RFB server which encoding types we accept. Put them
1160 * in order of preference, if we have any. We may always receive raw
1161 * encoding, even if we don't specify it here.
1165 uint8_t type; /* always rfbSetEncodings */
1167 uint16_t nEncodings;
1168 /* followed by nEncodings * uint32_t encoding types */
1169 } rfbSetEncodingsMsg;
1171 #define sz_rfbSetEncodingsMsg 4
1174 /*-----------------------------------------------------------------------------
1175 * FramebufferUpdateRequest - request for a framebuffer update. If incremental
1176 * is true then the client just wants the changes since the last update. If
1177 * false then it wants the whole of the specified rectangle.
1181 uint8_t type; /* always rfbFramebufferUpdateRequest */
1182 uint8_t incremental;
1187 } rfbFramebufferUpdateRequestMsg;
1189 #define sz_rfbFramebufferUpdateRequestMsg 10
1192 /*-----------------------------------------------------------------------------
1193 * KeyEvent - key press or release
1195 * Keys are specified using the "keysym" values defined by the X Window System.
1196 * For most ordinary keys, the keysym is the same as the corresponding ASCII
1197 * value. Other common keys are:
1201 * Return or Enter 0xff0d
1224 uint8_t type; /* always rfbKeyEvent */
1225 uint8_t down; /* true if down (press), false if up */
1227 uint32_t key; /* key is specified as an X keysym */
1230 #define sz_rfbKeyEventMsg 8
1233 /*-----------------------------------------------------------------------------
1234 * PointerEvent - mouse/pen move and/or button press.
1238 uint8_t type; /* always rfbPointerEvent */
1239 uint8_t buttonMask; /* bits 0-7 are buttons 1-8, 0=up, 1=down */
1242 } rfbPointerEventMsg;
1244 #define rfbButton1Mask 1
1245 #define rfbButton2Mask 2
1246 #define rfbButton3Mask 4
1247 #define rfbButton4Mask 8
1248 #define rfbButton5Mask 16
1249 /* RealVNC 335 method */
1250 #define rfbWheelUpMask rfbButton4Mask
1251 #define rfbWheelDownMask rfbButton5Mask
1253 #define sz_rfbPointerEventMsg 6
1257 /*-----------------------------------------------------------------------------
1258 * ClientCutText - the client has new text in its cut buffer.
1262 uint8_t type; /* always rfbClientCutText */
1266 /* followed by char text[length] */
1267 } rfbClientCutTextMsg;
1269 #define sz_rfbClientCutTextMsg 8
1273 /*-----------------------------------------------------------------------------
1274 * sf@2002 - Set Server Scale
1275 * SetServerScale - Server must change the scale of the client buffer.
1278 typedef struct _rfbSetScaleMsg {
1279 uint8_t type; /* always rfbSetScale */
1280 uint8_t scale; /* Scale value 1<sv<n */
1284 #define sz_rfbSetScaleMsg 4
1287 /*-----------------------------------------------------------------------------
1288 * Copyright (C) 2001 Harakan Software
1289 * PalmVNC 1.4 & 2.? SetScale Factor message
1290 * SetScaleFactor - tell the RFB server to alter the scale factor for the
1294 uint8_t type; /* always rfbPalmVNCSetScaleFactor */
1296 uint8_t scale; /* Scale factor (positive non-zero integer) */
1298 } rfbPalmVNCSetScaleFactorMsg;
1300 #define sz_rfbPalmVNCSetScaleFactorMsg (4)
1303 /*-----------------------------------------------------------------------------
1304 * rdv@2002 - Set input status
1305 * SetServerInput - Server input is dis/enabled
1308 typedef struct _rfbSetServerInputMsg {
1309 uint8_t type; /* always rfbSetScale */
1310 uint8_t status; /* Scale value 1<sv<n */
1312 } rfbSetServerInputMsg;
1314 #define sz_rfbSetServerInputMsg 4
1316 /*-----------------------------------------------------------------------------
1318 * SetSW - Server SW/full desktop
1321 typedef struct _rfbSetSWMsg {
1322 uint8_t type; /* always rfbSetSW */
1328 #define sz_rfbSetSWMsg 6
1331 /*-----------------------------------------------------------------------------
1332 * Union of all client->server messages.
1337 rfbSetPixelFormatMsg spf;
1338 rfbFixColourMapEntriesMsg fcme;
1339 rfbSetEncodingsMsg se;
1340 rfbFramebufferUpdateRequestMsg fur;
1342 rfbPointerEventMsg pe;
1343 rfbClientCutTextMsg cct;
1345 rfbPalmVNCSetScaleFactorMsg pssf;
1346 rfbSetServerInputMsg sim;
1347 rfbFileTransferMsg ft;
1350 } rfbClientToServerMsg;
1353 * vncauth.h - describes the functions provided by the vncauth library.
1357 #define CHALLENGESIZE 16
1359 extern int rfbEncryptAndStorePasswd(char *passwd, char *fname);
1360 extern char *rfbDecryptPasswdFromFile(char *fname);
1361 extern void rfbRandomBytes(unsigned char *bytes);
1362 extern void rfbEncryptBytes(unsigned char *bytes, char *passwd);