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.
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.
The Authentication message is just the same as in RFB.
Table 2. Authentication
No. of bytes | Type | Value | Description | |
---|---|---|---|---|
4 | uint32_t | authentication-scheme: | ||
0 | connection failed | |||
1 | no authentication | |||
2 | VNC 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 bytes | Type | Value | Description | |
---|---|---|---|---|
4 | uint32_t | reason-length | ||
reason-length | uint8_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.
The RVC server advertises to the client which features it can provide using the ServerInitialisation message.
Table 4. ServerInitialisation
No. of bytes | Type | Value | Description | |
---|---|---|---|---|
1 | uint8_t | 0 | message-type | |
1 | uint8_t | num-features | ||
num-features | uint8_t[] | feature-list |
Features that can appear in the feature-list are:
Table 5. Features
Feature | Description | |
---|---|---|
0 | Key message | |
1 | Pointer message | |
2 | Incremental rectangle updates | |
3 | Incremental scroll updates | |
4 | Clear screen updates | |
5 | Console cropping | |
6 | Console switch reporting | |
7 | Console display locking | |
8 | Console input locking | |
9 | Shareable session | |
10 | VNC server integration | |
11 | Console switching | |
12 | Console pushing |
The ClientInitialisation is a response to the ServerInitialisation message.
Table 6. ClientInitialisation
No. of bytes | Type | Value | Description | |
---|---|---|---|---|
1 | uint8_t | 255 | message-type | |
3 | uint8_t[] | Padding | ||
4 | uint32_t | Minimum incremental update period (ms) | ||
1 | uint8_t | Rows | ||
1 | uint8_t | Columns | ||
1 | uint8_t | 0 | Special flags | |
1 | uint8_t | num-features | ||
num-features | uint8_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.
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.
If the Key feature is in use, the client can send a key to the RVC server.
If the Pointer feature is in use, the client can send a pointer event to the RVC server.
Table 9. Pointer
No. of bytes | Type | Value | Description |
---|---|---|---|
1 | uint8_t | 252 | message-type |
1 | uint8_t | x position | |
1 | uint8_t | y position | |
1 | uint8_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.
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.
If the incremental update feature is not in use, any IncrementalUpdate messages must cover the entire console area.
Table 12. IncrementalUpdate
No. of bytes | Type | Value | Description |
---|---|---|---|
1 | uint8_t | 1 | message-type |
1 | uint8_t | update-type: | |
0 | rectangle | ||
1 | scroll | ||
2 | clear | ||
2 | uint16_t | n | content-length |
n | uint8_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 bytes | Type | Value | Description |
---|---|---|---|
1 | uint8_t | x offset | |
1 | uint8_t | y offset | |
1 | uint8_t | rows | |
1 | uint8_t | columns | |
1 | uint8_t | x position | |
1 | uint8_t | y position | |
2*rows*columns | uint8_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:
For clear updates nothing else follows the header.
The intent of a clear update is to tell the client to clear its terminal.
If the console switch reporting feature is in use, this message may be sent.
Table 15. Switch
No. of bytes | Type | Value | Description |
---|---|---|---|
1 | uint8_t | 2 | message-type |
1 | uint8_t | virtual console number | |
2 | uint16_t | port number | |
1 | uint8_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.