Version 2

Font Manager

The fonts for a controller will be managed through a centralized Font Manager. Everything which wants fonts for rendering text will get them from the font manager.

Adding and Removing Fonts

The font manager will support adding and removing fonts on the fly. Thus all programs running on the controller which use fonts are expected to maintain a connection to the Font Manager, which will notify them about changes as they happen.

Caching

It is likely that font information will change rarely. Indeed, many controllers might go their entire lives without ever having their fonts changed. Since in many cases, communication with them from remote clients will be over a slow connection, it does not make sense to have to request full font information every time one wants to control the sign.

For this reason, each Font Manager will maintain an integer called its Cache Validity. The Cache Validity starts at 0 and is incremented every time that a font is added to, removed from, or changed in the Font Manager. Thus when a (remote) client requests a full set of font data, it will store the Cache Validity number along with the data. When it next connects to the Font Manager, it will first request the current Cache Validity. If the Cache Validities are equal, it can use the cached copy instead of requesting the font data. If the cache validity is different, it should discard its cached copy and requests a new set of data.

Protocol

The Font Manager Protocol is a variable-length packet based protocol which is initiated by a challenge-response authentication phase, followed by a versioning handshake.

The Font Manager will listen for connections using this protocol on port 40401.

Note: unless otherwise specified, all multi-byte integral types are in network-order (i.e. big-endian).

Challenge-Response Authentication

The protocol begins with a challenge-response exchange using the "network password" of the controller (the network password is described in the Data Sources specificaiton).

The Font Manager issues a unique 20 byte challenge. The correct response is the 20 byte SHA1 hash of the concatenation of the challenge and the secret password. (i.e. SHA1(challenge + password).) The initiator of the connection only gets one chance; if it does not return the correct response, the connection is terminated. Also, the connection is terminated if the complete response is not recieved within 90 seconds.

Handshake

The purpose of the handshake is to determine the version of the protocol to be used. The handshake packets do not contain a packet type because their required order make it redundant.

The handshake packets are, in order:

Font Manager -> Client Handshake Packet
Byte Count Data Type Value Description
1 unsigned byte 0 The maximum version of the protocol which is supported.
Client -> Font Manager Handshake Packet
Byte Count Data Type Value Description
1 unsigned byte 0 The version of the protocol to be used. This must be <= the maximum supported version sent by the Font Manager. If the Font Manager cannot support a version great enough, the client should simply drop the connection and report an error.

After the Handshake

After the handshake, this is an asynchronous protocol. The packets are mostly self-explanatory. Where they are not, they have notes describing their use.


Appendix A. Packet Definitions

Note: the data type String is defined as an unsigned short indicating length, followed by the specified number of bytes of UTF-8 data. All multi-byte integral types are in network order (i.e. big-endian) unless otherwise specified.

Font Information Packet
Byte Count Data Type Value Description
1 unsigned byte 0 Packet Type
2-65,535 String The font's name
1 unsigned byte the font's height (in pixels)
1 unsigned byte the spacing above the line
1 unsigned byte the spacing below the line
2 unsigned short (count) The number of characters in this font
Font Data Packet
Byte Count Data Type Value Description
1 unsigned byte 1 Packet Type
variable Font The font is embedded in this packet.
Notes:
When this packet is sent to the Font Manager, the font manager inserts it into its library. If it already has a font by this name, the font is replaced by this font. If the insertion is successful, the Font Manager sends a Font Information Packet which corresponds to this font. If the insertion is not successful, the Font Manager sends an Error Packet.
Error Packet
Byte Count Data Type Value Description
1 unsigned byte 2 Packet Type
2-65,537 String A human-readable error string explaining what caused the error.
Font Data List Packet
Byte Count Data Type Value Description
1 unsigned byte 3 Packet Type
4 unsigned integer Cache Validity
4 unsigned integer (count) The number of fonts in this list.
variable Font[count] The fonts.
Font Information Block
Byte Count Data Type Value Description
2-65,535 String The font's name
1 unsigned byte the font's height (in pixels)
1 unsigned byte the spacing above the line
1 unsigned byte the spacing below the line
Font Information List Packet
Byte Count Data Type Value Description
1 unsigned byte 4 Packet Type
4 unsigned integer Cache Validity
4 unsigned integer (count) The number of font information packets in this list.
variable Font Information Block[count] The Font Information Packets.
Font Information List Request Packet
Byte Count Data Type Value Description
1 unsigned byte 5 Packet Type
Font Data List Request Packet
Byte Count Data Type Value Description
1 unsigned byte 6 Packet Type
Font Data Request Packet
Byte Count Data Type Value Description
1 unsigned byte 7 Packet Type
2-65,537 String The name of the desired font.
Font Deletion Packet
Byte Count Data Type Value Description
1 unsigned byte 8 Packet Type
2-65,537 String The name of the font to delete from the Font Manager's library.
Notes:
Once the font has been deleted from the font's library, it then sends this packet as confirmation of the fact.
Font Character Information Request Packet
Byte Count Data Type Value Description
1 unsigned byte 9 Packet Type
2-65,537 String The name of the font to retrieve the character information for.
Character Information Block
Byte Count Data Type Value Description
2 unsigned short the Unicode character code of this character
1 unsigned byte The width of the character, in pixels
1 unsigned byte the spacing on the left
1 unsigned byte the spacing on the right
1 unsigned byte The layout direction of this character, as per the font format
Font Character Information Packet
Byte Count Data Type Value Description
1 unsigned byte 10 Packet Type
2-65,537 String The name of the font.
2 unsigned short (count) The number of characters in this font
1 unsigned byte The line height of the font (in pixels)
1 unsigned byte the spacing above the line
1 unsigned byte the spacing below the line
variable Character Information Block[count] The information blocks for each character.
Cache Validity Packet
Byte Count Data Type Value Description
1 unsigned byte 11 Packet Type
4 unsigned integer Cache Validity
Cache Validity Request Packet
Byte Count Data Type Value Description
1 unsigned byte 12 Packet Type
Notes:
The Font Manager should immediately respond with a Cache Validity Packet. See above.


Appendix B. Packet Types

Packet Type # Packet Type
0 Font Information Packet
1 Font Data Packet
2 Error Packet
3 Font Data List Packet
4 Font Information List Packet
5 Font Information List Request Packet
6 Font Data List Request Packet
7 Font Data Request Packet
8 Font Deletion Packet
9 Font Character Information Request Packet
10 Font Character Information Packet
11 Cache Validity Packet
12 Cache Validity Request Packet

Last modified: Fri Sep 17 09:19:23 Eastern Daylight Time 2004