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 |
Appendix B. Packet Types
Last modified: Fri Sep 17 09:19:23 Eastern Daylight Time 2004