RVC Protocol

The RVC protocol, like the RFB protocol, can operate over any reliable transport. RVC also has an initial handshaking phase.

The initial handshaking for RVC consists of ProtocolVersion, Authentication, ServerInitialisation and ClientInitialisation messages. Both sides of the protocol send ProtocolVersion; the feature set to use is negotiated in the initialisation messages.

The messages begin with a message-type byte followed by message-specific data. However, the message formats and their message types differ significantly from those in the RFB protocol.

The messages are in network byte order.

Handshake messages

ProtocolVersion

The server first sends the client a ProtocolVersion message, to which the client responds with a similar message detailing the protocol to actually use.

Minor increments in the version number should be feature additions (new messages/features) that the server may optionally provide.

Versions of the protocol that differ in major number are probably not compatible with one another.

The ProtocolVersion message is the same as in RFB: 12 ASCII bytes. For RVC, they are as follows.

Table 1. ProtocolVersion

No. of bytesValue
12"RVC 001.000\n" (hex 52 56 43 20 30 30 31 30 30 0a)

Authentication

The Authentication message is just the same as in RFB.

Table 2. Authentication

No. of bytesTypeValueDescription
4uint32_t authentication-scheme:
  0connection failed
  1no authentication
  2VNC authentication

This is followed by data specific to the authentication-scheme:

  • connection failed---for some reason the connection failed. This is followed by an ASCII string describing why.

    Table 3. connection failed

    No. of bytesTypeValueDescription
    4uint32_t reason-length
    reason-lengthuint8_t[] reason-string

    For connection-based transports, the server closes the connection after sending this message.

  • no authentication---no authentication is needed and the protocol continues to ServerInitialisation.

  • VNC authentication---VNC authentication is to be used. This is adequately described in the RFB protocol description and is not covered here.

ServerInitialisation

The RVC server advertises to the client which features it can provide using the ServerInitialisation message.

Table 4. ServerInitialisation

No. of bytesTypeValueDescription
1uint8_t0message-type
1uint8_t num-features
num-featuresuint8_t[] feature-list

Features that can appear in the feature-list are:

Table 5. Features

FeatureDescription
0Key message
1Pointer message
2Incremental rectangle updates
3Incremental scroll updates
4Clear screen updates
5Console cropping
6Console switch reporting
7Console display locking
8Console input locking
9Shareable session
10VNC server integration
11Console switching
12Console pushing

ClientInitialisation

The ClientInitialisation is a response to the ServerInitialisation message.

Table 6. ClientInitialisation

No. of bytesTypeValueDescription
1uint8_t255message-type
3uint8_t[] Padding
4uint32_t Minimum incremental update period (ms)
1uint8_t Rows
1uint8_t Columns
1uint8_t0Special flags
1uint8_t num-features
num-featuresuint8_t[] features-requested

The client specifies the minimum amount of time between unsolicited incremental updates in milliseconds.

It also specifies the number of rows and columns that it has. This information is only needed if the console cropping feature is used.

The features-requested array refers to the features advertised in the ServerInitialisation message; if num-features exceeds the number of features advertised, the excess are ignored.

A zero value for a feature request means that the feature must not be used; a value of 1 means that it may be used.

If the console pushing feature is in use, the server and client swap roles, and the original client must send the original server a ServerInitialisation message, which may not advertise the console pushing feature.

Client-originated messages

FullUpdateRequest

In order to request a full console update, the client uses this message. Incremental updates not covering the entire console area will not be sent by the server until it receives and responds to this message.

Table 7. FullUpdateRequest

No. of bytesTypeValueDescription
1uint8_t254message-type

Key

If the Key feature is in use, the client can send a key to the RVC server.

Table 8. Key

No. of bytesTypeValueDescription
1uint8_t253message-type
1uint8_t key

Pointer

If the Pointer feature is in use, the client can send a pointer event to the RVC server.

Table 9. Pointer

No. of bytesTypeValueDescription
1uint8_t252message-type
1uint8_t x position
1uint8_t y position
1uint8_t button-mask

The x and y positions are zero-based, from the top left hand corner. The current state of buttons 1 to 8 are represented by bits 0 to 7 of button-mask respectively, 0 meaning up, 1 meaning down.

SwitchRequest

A SwitchRequest can be used to try to change the active console. If successful, a Switch message will be generated (if allowed). Note that if the active console is under programmatic control, the switch request may silently fail.

Table 10. SwitchRequest

No. of bytesTypeValueDescription
1uint8_t251message-type
1uint8_t virtual console number

Terminate

A Terminate message causes the server to go back to its initial state (awaiting ProtocolVersion), if the connection is still valid.

Table 11. Terminate

No. of bytesTypeValueDescription
1uint8_t128message-type

Server-originated messages

IncrementalUpdate

If the incremental update feature is not in use, any IncrementalUpdate messages must cover the entire console area.

Table 12. IncrementalUpdate

No. of bytesTypeValueDescription
1uint8_t1message-type
1uint8_t update-type:
  0rectangle
  1scroll
  2clear
2uint16_tncontent-length
nuint8_t[] contents

A client must support rectangle type updates. Other types of update will only be sent if the corresponding feature is in use.

The header is followed by type-specific data.

  • For rectangle updates the header is followed by:

    Table 13. rectangle

    No. of bytesTypeValueDescription
    1uint8_t x offset
    1uint8_t y offset
    1uint8_t rows
    1uint8_t columns
    1uint8_t x position
    1uint8_t y position
    2*rows*columnsuint8_t[] contents

    The contents are sent in rows, with the first byte of a (row,column) entry being the character at that position, and the second being the attributes. The attribute byte takes the form of VGA text mode character attributes.

  • For scroll updates the header is followed by:

    Table 14. scroll

    No. of bytesTypeValueDescription
    1uint8_t lines to scroll
  • For clear updates nothing else follows the header.

    The intent of a clear update is to tell the client to clear its terminal.

Switch

If the console switch reporting feature is in use, this message may be sent.

Table 15. Switch

No. of bytesTypeValueDescription
1uint8_t2message-type
1uint8_t virtual console number
2uint16_t port number
1uint8_t mode (0 for text)

The port number is one on which an RFB server is accepting connections for that display, or zero if there is no such server.

Terminate

A Terminate message causes the client to go back to its initial state (send ProtocolVersion), if the connection is still valid.

Table 16. Terminate

No. of bytesTypeValueDescription
1uint8_t128message-type