Internet Engineering Task Force (IETF) T. Richardson
Request for Comments: 6143 J. Levine
Category: Informational RealVNC Ltd.
ISSN: 2070-1721 March 2011
The Remote Framebuffer Protocol
Abstract
RFB ("remote framebuffer") is a simple protocol for remote access to
graphical user interfaces that allows a client to view and control a
window system on another computer. Because it works at the
framebuffer level, RFB is applicable to all windowing systems and
applications. This document describes the protocol used to
communicate between an RFB client and RFB server. RFB is the
protocol used in VNC.
Status of This Memo
This document is not an Internet Standards Track specification; it is
published for informational purposes.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Not all documents
approved by the IESG are a candidate for any level of Internet
Standard; see Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc6143.
Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Richardson & Levine Informational [Page 1]
RFC 6143 The Remote Framebuffer Protocol March 2011
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Initial Connection . . . . . . . . . . . . . . . . . . . . . . 4
3. Display Protocol . . . . . . . . . . . . . . . . . . . . . . . 4
4. Input Protocol . . . . . . . . . . . . . . . . . . . . . . . . 5
5. Representation of Pixel Data . . . . . . . . . . . . . . . . . 5
6. Protocol Versions and Extensions . . . . . . . . . . . . . . . 6
7. Protocol Messages . . . . . . . . . . . . . . . . . . . . . . 7
7.1. Handshake Messages . . . . . . . . . . . . . . . . . . . . 8
7.1.1. ProtocolVersion Handshake . . . . . . . . . . . . . . 8
7.1.2. Security Handshake . . . . . . . . . . . . . . . . . . 8
7.1.3. SecurityResult Handshake . . . . . . . . . . . . . . . 10
7.2. Security Types . . . . . . . . . . . . . . . . . . . . . . 10
7.2.1. None . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.2.2. VNC Authentication . . . . . . . . . . . . . . . . . . 10
7.3. Initialization Messages . . . . . . . . . . . . . . . . . 11
7.3.1. ClientInit . . . . . . . . . . . . . . . . . . . . . . 11
7.3.2. ServerInit . . . . . . . . . . . . . . . . . . . . . . 11
7.4. Pixel Format Data Structure . . . . . . . . . . . . . . . 12
7.5. Client-to-Server Messages . . . . . . . . . . . . . . . . 13
7.5.1. SetPixelFormat . . . . . . . . . . . . . . . . . . . . 13
7.5.2. SetEncodings . . . . . . . . . . . . . . . . . . . . . 14
7.5.3. FramebufferUpdateRequest . . . . . . . . . . . . . . . 15
7.5.4. KeyEvent . . . . . . . . . . . . . . . . . . . . . . . 16
7.5.5. PointerEvent . . . . . . . . . . . . . . . . . . . . . 19
7.5.6. ClientCutText . . . . . . . . . . . . . . . . . . . . 19
7.6. Server-to-Client Messages . . . . . . . . . . . . . . . . 20
7.6.1. FramebufferUpdate . . . . . . . . . . . . . . . . . . 20
7.6.2. SetColorMapEntries . . . . . . . . . . . . . . . . . . 21
7.6.3. Bell . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.6.4. ServerCutText . . . . . . . . . . . . . . . . . . . . 22
7.7. Encodings . . . . . . . . . . . . . . . . . . . . . . . . 22
7.7.1. Raw Encoding . . . . . . . . . . . . . . . . . . . . . 23
7.7.2. CopyRect Encoding . . . . . . . . . . . . . . . . . . 23
7.7.3. RRE Encoding . . . . . . . . . . . . . . . . . . . . . 23
7.7.4. Hextile Encoding . . . . . . . . . . . . . . . . . . . 24
7.7.5. TRLE . . . . . . . . . . . . . . . . . . . . . . . . . 27
7.7.6. ZRLE . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.8. Pseudo-Encodings . . . . . . . . . . . . . . . . . . . . . 30
7.8.1. Cursor Pseudo-Encoding . . . . . . . . . . . . . . . . 30
7.8.2. DesktopSize Pseudo-Encoding . . . . . . . . . . . . . 31
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31
8.1. RFB Security Types . . . . . . . . . . . . . . . . . . . . 32
8.1.1. Registry Name . . . . . . . . . . . . . . . . . . . . 32
8.1.2. Registry Contents . . . . . . . . . . . . . . . . . . 32
8.2. Client-to-Server Message Types . . . . . . . . . . . . . . 32
8.2.1. Registry Name . . . . . . . . . . . . . . . . . . . . 32
Richardson & Levine Informational [Page 2]
RFC 6143 The Remote Framebuffer Protocol March 2011
8.2.2. Registry Contents . . . . . . . . . . . . . . . . . . 32
8.3. Server-to-Client Message Types . . . . . . . . . . . . . . 33
8.3.1. Registry Name . . . . . . . . . . . . . . . . . . . . 33
8.3.2. Registry Contents . . . . . . . . . . . . . . . . . . 33
8.4. RFB Encoding Types . . . . . . . . . . . . . . . . . . . . 34
8.4.1. Registry Name . . . . . . . . . . . . . . . . . . . . 34
8.4.2. Registry Contents . . . . . . . . . . . . . . . . . . 34
9. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 36
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 36
11.1. Normative References . . . . . . . . . . . . . . . . . . . 36
11.2. Informative References . . . . . . . . . . . . . . . . . . 36
Appendix A. Differences in Earlier Protocol Versions . . . . . . 38
A.1. Differences in the Version 3.3 Protocol . . . . . . . . . 38
A.2. Differences in the Version 3.7 Protocol . . . . . . . . . 38
1. Introduction
RFB ("remote framebuffer") is a simple protocol for remote access to
graphical user interfaces. Because it works at the framebuffer
level, it is applicable to all windowing systems and applications,
including X11, Windows, and Macintosh. RFB is the protocol used in
VNC. The protocol is widely implemented and has had fairly good
interoperability.
The remote endpoint where the user sits (typically with a display,
keyboard, and pointer) is called the RFB client or viewer. The
endpoint where changes to the framebuffer originate (i.e., the
windowing system and applications) is known as the RFB server.
RFB is a "thin client" protocol. The emphasis in the design of the
RFB protocol is to make very few requirements of the client. In this
way, clients can run on the widest range of hardware, and the task of
implementing a client is made as simple as possible.
The protocol also makes the client stateless. If a client
disconnects from a given server and subsequently reconnects to that
same server, the state of the user interface is preserved.
Furthermore, a different client endpoint can be used to connect to
the same RFB server. At the new endpoint, the user will see exactly
the same graphical user interface as at the original endpoint. In
effect, the interface to the user's applications becomes completely
mobile. Wherever suitable network connectivity exists, the user can
access their own personal applications, and the state of these
applications is preserved between accesses from different locations.
This provides the user with a familiar, uniform view of the computing
infrastructure wherever they go.
Richardson & Levine Informational [Page 3]
RFC 6143 The Remote Framebuffer Protocol March 2011
The RFB protocol has evolved over the past decade, and has been
implemented several times, including at least one open source
version. This document describes the RFB protocol as actually
implemented, so that future implementers can interoperate with
existing clients and servers.
2. Initial Connection
An RFB server is typically a long-lived process that maintains the
state of a framebuffer. RFB clients typically connect, communicate
with the server for a period of time to use and manipulate the
framebuffer, then disconnect. A subsequent RFB session will then
pick up where a prior session left off, with the state of the
framebuffer intact.
An RFB client contacts the server on TCP port 5900. On systems with
multiple RFB servers, server N typically listens on port 5900+N,
analogous to the way that X Window servers listen on port 6000+N.
Some browser-based clients use a Java application to run the RFB
protocol. RFB servers sometimes provide a simple HTTP server on port
5800 that provides the requisite Java applet.
In some cases, the initial roles of the client and server are
reversed, with the RFB client listening on port 5500, and the RFB
server contacting the RFB client. Once the connection is
established, the two sides take their normal roles, with the RFB
server sending the first handshake message.
Note that the only port number assigned by IANA for RFB is port 5900,
so RFB clients and servers should avoid using other port numbers
unless they are communicating with servers or clients known to use
the non-standard ports.
3. Display Protocol
The display side of the protocol is based around a single graphics
primitive: "put a rectangle of pixel data at a given x,y position".
This might seem an inefficient way of drawing many user interface
components. However, allowing various different encodings for the
pixel data gives us a large degree of flexibility in how to trade off
various parameters such as network bandwidth, client drawing speed,
and server processing speed.
Richardson & Levine Informational [Page 4]
RFC 6143 The Remote Framebuffer Protocol March 2011
A sequence of these rectangles makes a framebuffer update (simply
referred to here as "update"). An update represents a change from
one valid framebuffer state to another, so in some ways is similar to
a frame of video. The rectangles in an update are usually but not
always disjoint.
The update protocol is demand-driven by the client. That is, an
update is only sent from the server to the client in response to an
explicit request from the client. This gives the protocol an
adaptive quality. The slower the client and the network are, the
lower the rate of updates. With typical applications, changes to the
same area of the framebuffer tend to happen soon after one another.
With a slow client or network, transient states of the framebuffer
can be ignored, resulting in less network traffic and less drawing
for the client.
After the initial handshake sequence, the protocol is asynchronous,
with each side sending messages as needed. The server must not send
unsolicited updates. An update must only be sent in response to a
request from the client. When several requests from the client are
outstanding, a single update from the server may satisfy all of them.
4. Input Protocol
The input side of the protocol is based on a standard workstation
model of a keyboard and multi-button pointing device. Input events
are simply sent to the server by the client whenever the user presses
a key or pointer button, or whenever the pointing device is moved.
These input events can also be synthesized from other non-standard
I/O devices. For example, a pen-based handwriting recognition engine
might generate keyboard events.
5. Representation of Pixel Data
Initial interaction between the RFB client and server involves a
negotiation of the format and encoding of the pixel data that will be
sent. This negotiation has been designed to make the job of the
client as easy as possible. The server must always be able to supply
pixel data in the form the client wants. However, if the client is
able to cope equally with several different formats or encodings, it
may choose one that is easier for the server to produce.
Pixel format refers to the representation of individual colors by
pixel values. The most common pixel formats are 24-bit or 16-bit
"true color", where bit-fields within the pixel value translate
directly to red, green, and blue intensities, and 8-bit "color map"
(palette) where the pixel values are indices into a 256-entry table
that contains the actual RGB intensities.
Richardson & Levine Informational [Page 5]
RFC 6143 The Remote Framebuffer Protocol March 2011
Encoding refers to the way that a rectangle of pixel data will be
sent to the client. Every rectangle of pixel data is prefixed by a
header giving the X,Y position of the rectangle on the screen, the
width and height of the rectangle, and an encoding type which
specifies the encoding of the pixel data. The data itself then
follows using the specified encoding.
The encoding types defined at present are: Raw, CopyRect, RRE, TRLE,
Hextile, and ZRLE. In practice, current servers use the ZRLE, TRLE,
and CopyRect encodings since they provide the best compression for
typical desktops. Clients generally also support Hextile, which was
often used by older RFB servers that didn't support TRLE. See
Section 7.7 for a description of each of the encodings.
6. Protocol Versions and Extensions
The RFB protocol has evolved through three published versions: 3.3,
3.7, and 3.8. This document primarily documents the final version
3.8; differences from the earlier versions, which are minor, are
described in Appendix A. Under no circumstances should an
implementation use a protocol version number other than one defined
in this document. Over the years, different implementations of RFB
have attempted to use different version numbers to add undocumented
extensions, with the result being that to interoperate, any unknown
3.x version must be treated as 3.3, so it is not possible to add a
3.9 or higher version in a backward-compatible fashion. Future
evolution of RFB will use 4.x version numbers.
It is not necessary to change the protocol version number to extend
the protocol. The protocol can be extended within an existing
version by:
New encodings
A new encoding type can be added to the protocol relatively easily
while maintaining compatibility with existing clients and servers.
Existing servers will simply ignore requests for a new encoding
that they don't support. Existing clients will never request the
new encoding so will never see rectangles encoded that way.
Pseudo-encodings
In addition to genuine encodings, a client can request a "pseudo-
encoding" to declare to the server that it supports a certain
extension to the protocol. A server that does not support the
extension will simply ignore the pseudo-encoding. Note that this
means the client must assume that the server does not support the
extension until it gets some extension-specific confirmation from
the server. See Section 7.8 for a description of current pseudo-
encodings.
Richardson & Levine Informational [Page 6]
RFC 6143 The Remote Framebuffer Protocol March 2011
New security types
Adding a new security type gives full flexibility in modifying the
behavior of the protocol without sacrificing compatibility with
existing clients and servers. A client and server that agree on a
new security type can effectively talk whatever protocol they like
after that -- it doesn't necessarily have to be anything like the
RFB protocol.
See Section 8 for information on obtaining an ID for a new encoding
or security type.
7. Protocol Messages
The RFB protocol can operate over any reliable transport, either
byte-stream or message based. It usually operates over a TCP/IP
connection. There are three stages to the protocol. First is the
handshaking phase, the purpose of which is to agree upon the protocol
version and the type of security to be used. The second stage is an
initialization phase where the client and server exchange ClientInit
and ServerInit messages. The final stage is the normal protocol
interaction. The client can send whichever messages it wants, and
may receive messages from the server as a result. All these messages
begin with a message-type byte, followed by message-specific data.
The following descriptions of protocol messages use the basic types
U8, U16, U32, S8, S16, and S32. These represent, respectively, 8-,
16-, and 32-bit unsigned integers and 8-, 16-, and 32-bit signed
integers. All multiple-byte integers (other than pixel values
themselves) are in big endian order (most significant byte first).
Some messages use arrays of the basic types, with the number of
entries in the array determined from fields preceding the array.
The type PIXEL means a pixel value of bytesPerPixel bytes, where
bytesPerPixel is the number of bits-per-pixel divided by 8. The
bits-per-pixel is agreed by the client and server, either in the
ServerInit message (Section 7.3.2) or a SetPixelFormat message
(Section 7.5.1). See Section 7.4 for the detailed description of the
pixel format.
Several message formats include padding bits or bytes. For maximum
compatibility, messages should be generated with padding set to zero,
but message recipients should not assume padding has any particular
value.
Richardson & Levine Informational [Page 7]
RFC 6143 The Remote Framebuffer Protocol March 2011
7.1. Handshake Messages
When an RFB client and server first connect, they exchange a sequence
of handshake messages that determine the protocol version, what type
of connection security (if any) to use, a password check if the
security type requires it, and some initialization information.
7.1.1. ProtocolVersion Handshake
Handshaking begins by the server sending the client a ProtocolVersion
message. This lets the client know which is the highest RFB protocol
version number supported by the server. The client then replies with
a similar message giving the version number of the protocol that
should actually be used (which may be different to that quoted by the
server). A client should never request a protocol version higher
than that offered by the server. It is intended that both clients
and servers may provide some level of backwards compatibility by this
mechanism.
The only published protocol versions at this time are 3.3, 3.7, and
3.8. Other version numbers are reported by some servers and clients,
but should be interpreted as 3.3 since they do not implement the
different handshake in 3.7 or 3.8. Addition of a new encoding or
pseudo-encoding type does not require a change in protocol version,
since a server can simply ignore encodings it does not understand.
The ProtocolVersion message consists of 12 bytes interpreted as a
string of ASCII characters in the format "RFB xxx.yyy\n" where xxx
and yyy are the major and minor version numbers, left-padded with
zeros:
RFB 003.008\n (hex 52 46 42 20 30 30 33 2e 30 30 38 0a)
7.1.2. Security Handshake
Once the protocol version has been decided, the server and client
must agree on the type of security to be used on the connection. The
server lists the security types that it supports:
+--------------------------+-------------+--------------------------+
| No. of bytes | Type | Description |
| | [Value] | |
+--------------------------+-------------+--------------------------+
| 1 | U8 | number-of-security-types |
| number-of-security-types | U8 array | security-types |
+--------------------------+-------------+--------------------------+
Richardson & Levine Informational [Page 8]
RFC 6143 The Remote Framebuffer Protocol March 2011
If the server listed at least one valid security type supported by
the client, the client sends back a single byte indicating which
security type is to be used on the connection:
+--------------+--------------+---------------+
| No. of bytes | Type [Value] | Description |
+--------------+--------------+---------------+
| 1 | U8 | security-type |
+--------------+--------------+---------------+
If number-of-security-types is zero, then for some reason the
connection failed (e.g., the server cannot support the desired
protocol version). This is followed by a string describing the
reason (where a string is specified as a length followed by that many
ASCII characters):
+---------------+--------------+---------------+
| No. of bytes | Type [Value] | Description |
+---------------+--------------+---------------+
| 4 | U32 | reason-length |
| reason-length | U8 array | reason-string |
+---------------+--------------+---------------+
The server closes the connection after sending the reason-string.
The security types defined in this document are:
+--------+--------------------+
| Number | Name |
+--------+--------------------+
| 0 | Invalid |
| 1 | None |
| 2 | VNC Authentication |
+--------+--------------------+
Other security types exist but are not publicly documented.
Once the security-type has been decided, data specific to that
security-type follows (see Section 7.2 for details). At the end of
the security handshaking phase, the protocol normally continues with
the SecurityResult message.
Note that after the security handshaking phase, it is possible that
further communication is over an encrypted or otherwise altered
channel if the two ends agree on an extended security type beyond the
ones described here.
Richardson & Levine Informational [Page 9]
RFC 6143 The Remote Framebuffer Protocol March 2011
7.1.3. SecurityResult Handshake
The server sends a word to inform the client whether the security
handshaking was successful.
+--------------+--------------+-------------+
| No. of bytes | Type [Value] | Description |
+--------------+--------------+-------------+
| 4 | U32 | status: |
| | 0 | OK |
| | 1 | failed |
+--------------+--------------+-------------+
If successful, the protocol passes to the initialization phase
(Section 7.3).
If unsuccessful, the server sends a string describing the reason for
the failure, and then closes the connection:
+---------------+--------------+---------------+
| No. of bytes | Type [Value] | Description |
+---------------+--------------+---------------+
| 4 | U32 | reason-length |
| reason-length | U8 array | reason-string |
+---------------+--------------+---------------+
7.2. Security Types
Two security types are defined here.
7.2.1. None
No authentication is needed. The protocol continues with the
SecurityResult message.
7.2.2. VNC Authentication
VNC authentication is to be used. The server sends a random 16-byte
challenge:
+--------------+--------------+-------------+
| No. of bytes | Type [Value] | Description |
+--------------+--------------+-------------+
| 16 | U8 | challenge |
+--------------+--------------+-------------+
Richardson & Levine Informational [Page 10]
RFC 6143 The Remote Framebuffer Protocol March 2011
The client encrypts the challenge with DES, using a password supplied
by the user as the key. To form the key, the password is truncated
to eight characters, or padded with null bytes on the right. The
client then sends the resulting 16-byte response:
+--------------+--------------+-------------+
| No. of bytes | Type [Value] | Description |
+--------------+--------------+-------------+
| 16 | U8 | response |
+--------------+--------------+-------------+
The protocol continues with the SecurityResult message.
This type of authentication is known to be cryptographically weak and
is not intended for use on untrusted networks. Many implementations
will want to use stronger security, such as running the session over
an encrypted channel provided by IPsec [RFC4301] or SSH [RFC4254].
7.3. Initialization Messages
Once the client and server agree on and perhaps validate a security
type, the protocol passes to the initialization stage. The client
sends a ClientInit message. Then, the server sends a ServerInit
message.
7.3.1. ClientInit
+--------------+--------------+-------------+
| No. of bytes | Type [Value] | Description |
+--------------+--------------+-------------+
| 1 | U8 | shared-flag |
+--------------+--------------+-------------+
Shared-flag is non-zero (true) if the server should try to share the
desktop by leaving other clients connected, and zero (false) if it
should give exclusive access to this client by disconnecting all
other clients.
7.3.2. ServerInit
After receiving the ClientInit message, the server sends a ServerInit
message. This tells the client the width and height of the server's
framebuffer, its pixel format, and the name associated with the
desktop:
Richardson & Levine Informational [Page 11]
RFC 6143 The Remote Framebuffer Protocol March 2011
+--------------+--------------+------------------------------+
| No. of bytes | Type [Value] | Description |
+--------------+--------------+------------------------------+
| 2 | U16 | framebuffer-width in pixels |
| 2 | U16 | framebuffer-height in pixels |
| 16 | PIXEL_FORMAT | server-pixel-format |
| 4 | U32 | name-length |
| name-length | U8 array | name-string |
+--------------+--------------+------------------------------+
Server-pixel-format specifies the server's natural pixel format.
This pixel format will be used unless the client requests a different
format using the SetPixelFormat message (Section 7.5.1).
7.4. Pixel Format Data Structure
Several server-to-client messages include a PIXEL_FORMAT, a 16-byte
structure that describes the way a pixel is transmitted.
+--------------+--------------+-----------------+
| No. of bytes | Type [Value] | Description |
+--------------+--------------+-----------------+
| 1 | U8 | bits-per-pixel |
| 1 | U8 | depth |
| 1 | U8 | big-endian-flag |
| 1 | U8 | true-color-flag |
| 2 | U16 | red-max |
| 2 | U16 | green-max |
| 2 | U16 | blue-max |
| 1 | U8 | red-shift |
| 1 | U8 | green-shift |
| 1 | U8 | blue-shift |
| 3 | | padding |
+--------------+--------------+-----------------+
Bits-per-pixel is the number of bits used for each pixel value on the
wire. This must be greater than or equal to the depth, which is the
number of useful bits in the pixel value. Currently bits-per-pixel
must be 8, 16, or 32. Big-endian-flag is non-zero (true) if multi-
byte pixels are interpreted as big endian. Although the depth should
be consistent with the bits-per-pixel and the various -max values,
clients do not use it when interpreting pixel data.
If true-color-flag is non-zero (true), then the last six items
specify how to extract the red, green, and blue intensities from the
pixel value. Red-max is the maximum red value and must be 2^N - 1,
where N is the number of bits used for red. Note the -max values are
always in big endian order. Red-shift is the number of shifts needed
Richardson & Levine Informational [Page 12]
RFC 6143 The Remote Framebuffer Protocol March 2011
to get the red value in a pixel to the least significant bit. Green-
max, green-shift, blue-max, and blue-shift are similar for green and
blue. For example, to find the red value (between 0 and red-max)
from a given pixel, do the following:
o Swap the pixel value according to big-endian-flag, e.g., if big-
endian-flag is zero (false) and host byte order is big endian,
then swap.
o Shift right by red-shift.
o AND with red-max (in host byte order).
If true-color-flag is zero (false), then the server uses pixel values
that are not directly composed from the red, green, and blue
intensities, but serve as indices into a color map. Entries in the
color map are set by the server using the SetColorMapEntries message
(See Section 7.6.2).
7.5. Client-to-Server Messages
The client-to-server message types defined in this document are:
+--------+--------------------------+
| Number | Name |
+--------+--------------------------+
| 0 | SetPixelFormat |
| 2 | SetEncodings |
| 3 | FramebufferUpdateRequest |
| 4 | KeyEvent |
| 5 | PointerEvent |
| 6 | ClientCutText |
+--------+--------------------------+
Other message types exist but are not publicly documented. Before
sending a message other than those described in this document, a
client must have determined that the server supports the relevant
extension by receiving an appropriate extension-specific confirmation
from the server.
7.5.1. SetPixelFormat
A SetPixelFormat message sets the format in which pixel values should
be sent in FramebufferUpdate messages. If the client does not send a
SetPixelFormat message, then the server sends pixel values in its
natural format as specified in the ServerInit message
(Section 7.3.2).
Richardson & Levine Informational [Page 13]
RFC 6143 The Remote Framebuffer Protocol March 2011
If true-color-flag is zero (false), then this indicates that a "color
map" is to be used. The server can set any of the entries in the
color map using the SetColorMapEntries message (Section 7.6.2).
Immediately after the client has sent this message, the contents of
the color map are undefined, even if entries had previously been set
by the server.
+--------------+--------------+--------------+
| No. of bytes | Type [Value] | Description |
+--------------+--------------+--------------+
| 1 | U8 [0] | message-type |
| 3 | | padding |
| 16 | PIXEL_FORMAT | pixel-format |
+--------------+--------------+--------------+
PIXEL_FORMAT is as described in Section 7.4.
7.5.2. SetEncodings
A SetEncodings message sets the encoding types in which pixel data
can be sent by the server. The order of the encoding types given in
this message is a hint by the client as to its preference (the first
encoding specified being most preferred). The server may or may not
choose to make use of this hint. Pixel data may always be sent in
raw encoding even if not specified explicitly here.
In addition to genuine encodings, a client can request "pseudo-
encodings" to declare to the server that it supports certain
extensions to the protocol. A server that does not support the
extension will simply ignore the pseudo-encoding. Note that this
means the client must assume that the server does not support the
extension until it gets some extension-specific confirmation from the
server.
See Section 7.7 for a description of each encoding and Section 7.8
for the meaning of pseudo-encodings.
+--------------+--------------+---------------------+
| No. of bytes | Type [Value] | Description |
+--------------+--------------+---------------------+
| 1 | U8 [2] | message-type |
| 1 | | padding |
| 2 | U16 | number-of-encodings |
+--------------+--------------+---------------------+
Richardson & Levine Informational [Page 14]
RFC 6143 The Remote Framebuffer Protocol March 2011
This is followed by number-of-encodings repetitions of the following:
+--------------+--------------+---------------+
| No. of bytes | Type [Value] | Description |
+--------------+--------------+---------------+
| 4 | S32 | encoding-type |
+--------------+--------------+---------------+
7.5.3. FramebufferUpdateRequest
A FramebufferUpdateRequest message notifies the server that the
client is interested in the area of the framebuffer specified by
x-position, y-position, width, and height. The server usually
responds to a FramebufferUpdateRequest by sending a
FramebufferUpdate. A single FramebufferUpdate may be sent in reply
to several FramebufferUpdateRequests.
The server assumes that the client keeps a copy of all parts of the
framebuffer in which it is interested. This means that normally the
server only needs to send incremental updates to the client.
If the client has lost the contents of a particular area that it
needs, then the client sends a FramebufferUpdateRequest with
incremental set to zero (false). This requests that the server send
the entire contents of the specified area as soon as possible. The
area will not be updated using the CopyRect encoding.
If the client has not lost any contents of the area in which it is
interested, then it sends a FramebufferUpdateRequest with incremental
set to non-zero (true). If and when there are changes to the
specified area of the framebuffer, the server will send a
FramebufferUpdate. Note that there may be an indefinite period
between the FramebufferUpdateRequest and the FramebufferUpdate.
In the case of a fast client, the client may want to regulate the
rate at which it sends incremental FramebufferUpdateRequests to avoid
excessive network traffic.
+--------------+--------------+--------------+
| No. of bytes | Type [Value] | Description |
+--------------+--------------+--------------+
| 1 | U8 [3] | message-type |
| 1 | U8 | incremental |
| 2 | U16 | x-position |
| 2 | U16 | y-position |
| 2 | U16 | width |
| 2 | U16 | height |
+--------------+--------------+--------------+
Richardson & Levine Informational [Page 15]
RFC 6143 The Remote Framebuffer Protocol March 2011
7.5.4. KeyEvent
A KeyEvent message indicates a key press or release. Down-flag is
non-zero (true) if the key is now pressed, and zero (false) if it is
now released. The key itself is specified using the "keysym" values
defined by the X Window System, even if the client or server is not
running the X Window System.
+--------------+--------------+--------------+
| No. of bytes | Type [Value] | Description |
+--------------+--------------+--------------+
| 1 | U8 [4] | message-type |
| 1 | U8 | down-flag |
| 2 | | padding |
| 4 | U32 | key |
+--------------+--------------+--------------+
For most ordinary keys, the keysym is the same as the corresponding
ASCII value. For full details, see [XLIBREF] or see the header file