Node:The User Area, Next:Writing Clients, Previous:LysKOM Content Types, Up:Top
The user area is a regular text that is used to store client-specific information in the server. Most clients use this to store settings a user has made that are specific to a particular server. There are also provisions to store settings that are shared between clients.
The user-area is divided into several sub-blocks. The common block is
shared by all clients, and its formats and contents are dictated by this
protocol specification. Clients may also create one or more other blocks.
In normal texts, everything up to the first line feed is considered to be the subject line. The user area is an exception: it does not contain any subject line.
Each block is encoded as a HOLLERITH string. A table of
contents is also encoded as a HOLLERITH string and added first
in the user area. There must be at last one space between each
string, and there might be spaces at the beginning and/or end of the
user-area. Thus, a user-area made up of three blocks will contain
four HOLLERITH-encoded strings, each separated by at least one
space, and maybe with extra spaces at the beginning or end of the
text.
The table of contents consists of one HOLLERITH-encoded string
for each block in the user-area. Each string contains the name of the
corresponding block. There is at least one space between each string,
and there may be spaces before the first string and after the last
string. Clients must never create two or more blocks with the same
name.
This format ensures that clients can copy or read past other clients' blocks without knowing their structure.
Example:
13H7Hblock-a 1Hb 4Hasdf 5H hjkl
In the above example, there are two blocks: block-a and
b. block-a contains four bytes, asdf, while
b contains five bytes: hjkl (note the leading
space). Below are a few other ways to encode the same user-area:
14H 7Hblock-a 1Hb 4Hasdf 5H hjkl
16H 7Hblock-a 1Hb 4Hasdf 5H hjkl
13H1Hb 7Hblock-a 5H hjkl 4Hasdf
The first two examples embed extra (redundant) spaces, and the last swaps the order of the two blocks.
The following block names have been defined:
common
elisp
WWW-kom
rkom
If you're writing a client that uses the user-area, please let us know what you name your client's block.
This defines the theoretical structure of the common block. The real world probably does not agree entirely with this, and it is likely to change just as soon as I have time to define something better. In the mean while you're probably better off ignoring the common block and storing all your settings in a client block. The Emacs lisp client uses the common block, but I have a feeling that it might store data that other clients can't read.
The common block contains a list of variable settings. Each variable setting consists of a name, some whitespace, and a value. Settings are separated by a line feed character. As of protocol version 10, values can be integers, strings, booleans or lists. The encoding is such that a value is encoded as a single protocol A token. That means that strings and lists are both encoded as HOLLERITHs. The reason for this is to simplify for clients that need to ignore the value, and so it is possible to add new value types without confusing old clients (new types will be encoded as HOLLERITHs.)
The grammar below sort of defines the syntax of the common block.
common-block : settings
settings : settings setting
| /* empty */
setting : variable ' ' value '\n'
variable : [A-Za-z-_0-9]+
value : boolean
| HOLLERITH
| list
| integer
boolean : 1 | 0
integer : -?[0-9]+
list : integer elems // Encoded in a HOLLERITH
elems : elems value
| empty
Currently the following variables are used, but more may be added, and as of protocol version 10, clients should be able to cope with variables they know nothing of in the common block, as long as they are of one of the types above. Pre-protocol version 10 clients can't deal with HOLLERITHs in the common block.
As of protocol 10 the following variables are stored in the common block:
created-texts-are-read
dashed-lines
presence-messages
print-number-of-unread-on-entrance
read-depth-first
reading-puts-comments-in-pointers-last
confirm-multiple-recipients
default-mark