html2
VM User's Manual: 21. VM Internals
21. VM Internals
This section gives a sketchy overview of the VM internals for the
developers/programmers.
21.1 Folder Internals
By default, VM stores mail folders in the Unix mbox
format,
described in the RFC 4155 specification of the Internet Engineering Task
Force. In this format, the mail folder is a text file consisting of a
sequence of messages, with each message consisting of a series of
headers followed by a message body. The beginning of each message is
delineated by a separator line starting with the string “From ” and
the end by a blank line. To make sure that such a line exists, VM adds
its own header line of the form “From VM ...” where the “...”
records the time at which VM first saw the message. The format of the
individual messages is as per the RFC 2822 specification, except that
Line-Feed characters may be used to delineate the end of lines in the
"Unix" format.
In addition to the Unix mbox format (which is called the From_
format), VM also handles the MMDF format and two versions of the System
V Unix format and the Emacs Rmail’s Babyl format. The variable
vm-folder-type
stores the type of the folder being used.
To every message, VM adds a header with the field name
“X-VM-v5-Data:” and stores in it the information about the message it
wishes to remember between sessions. This header line is used merely
for speed of processing. If, for any reason, a VM folder is
corrupted, it is safe to delete all the X-VM-v5-Data headers, and VM
will generate them afresh when the folder is visited.
The first message of the VM folder file contains additional headers that
VM uses for remembering information between sessions.
-
X-VM-Bookmark. This header stores the position of the cursor, as a
message number, in effect when VM saved the folder. Upon revisiting the
folder, VM attempts to put the cursor back at this position.
-
X-VM-Last-Modified.
-
X-VM-Message-Order. This header lists the order in which the messages
should be listed.
-
X-VM-Labels. This header lists the message labels that have been used in
the folder.
-
X-VM-VHeader. This header lists the visible headers that should be
displayed in message listings.
-
X-VM-Summary-Format. This header stores the format string for the
summary lines.
-
X-VM-POP-Retrieved. This header lists all the messages that have
been retrieved from POP servers together with the identifying
information for the POP servers. VM refrains from retrieving these
messages again in future in order to avoid duplication.
-
X-VM-IMAP-Retrieved. This header lists all the messages that have
been retrieved from IMAP servers together with the identifying
information for the IMAP servers. VM refrains from retrieving these
messages again in future in order to avoid duplication.
Internal to Emacs, VM stores the folder as simply a text buffer. However, it
remembers a variety of data about the message contents in the buffer
through internal variables.
-
vm-message-list
. A list of message data structures for all the
messages in the buffer.
-
vm-message-pointer
. A sublist of vm-message-list starting from
the current message that the cursor is on. So, the first element of
vm-message-pointer is the current message.
-
vm-last-message-pointer
. Whenever the cursor is moved, the
previous value of vm-message-pointer is remembered in this variable.
-
vm-folder-type
. The type of the current folder indicating how
the messages are stored: one of ’babyl, ’From_, ’BellFrom_,
’From_-with-Content-Length and ’mmdf.
-
vm-folder-access-method
. The method for accessing the server
message store: ’pop for pop-folders as well as local folders retrieving
messages from POP servers, ’imap for imap-folders as well as local
folders retrieving messages from IMAP servers, and nil for all other folders.
-
vm-folder-access-data
. A vector of data for accessing the server
message store. The first two elements of the vector are the maildrop
specification for the mail server and a reference to the process
connecting to the mail server. For the ’pop access method, that is all
there is. But, for the ’imap access method, the vector has 9 other
entries detailing various pieces of data about the IMAP server.
-
vm-virtual-folder-definition
. If the current folder is virtual,
then this variable holds the data constituting its definition.
-
vm-real-buffers
. If the current folder is virtual, then this
variable is a list of all the real folder buffers involved in
constructing it.
-
vm-virtual-buffers
. A list of all the virtual folder buffers
that the current buffer is involved in.
21.2 Message Internals
The message data structure is a vector containing various pieces of
data:
-
Location data. This data about the location of the various parts of the
message in the folder buffer is calculated after a folder is loaded and
parsed.
-
start. The starting position of the message, at which a leading
separator line begins.
-
headers. The position in the folder buffer where the headers of the message
start.
-
vheaders. The position in the folder buffer where the visible headers of the
message start. (The headers are rearranged in such a way that all the
visible headers are towards the end of the headers region.)
-
text. The position in the folder buffer where the text of the message starts.
-
text-end. The position in the folder buffer where the text of the message ends
-
end. The position in the folder buffer where the message ends.
-
Soft data. This vector contains other calculated data about the
message.
-
number. The message number as an integer.
-
padded number. The message number as a padded string.
-
mark. Flag that indicates if the message has been marked (via
vm-mark-message
).
-
su-start. The position in the summary buffer where the summary line of
the message starts.
-
su-end. The position in the summary buffer where the summary line of
the message ends.
-
real-message-sym. If the message is in a virtual folder, then its
corresponding “real message” is the underlying message in another
folder which is described by a message data structure similar to the
current one. The real message data structures are interned in an
obarray and represented by “symbols”. This field stores the symbol
representing the real message of the current message.
-
reverse-link. Link to the previous message in the message list.
-
message-type. A symbol indicating the type of the message according to
its folder type, one of
BellFrom_
, From_
and
From_-with-Content-Length
.
-
message-id-number. The unique id of the message.
-
buffer. The folder buffer of the message.
-
thread-indentation. Indentation level of the message in its message
thread.
-
babyl-frob-flag.
-
saved-virtual-attributes. Saved attributes if the message switched from
unmirrored to mirrored.
-
saved-virtual-mirror-data. Saved mirror data, if the message was
switched from unmirrored to mirrored.
-
virtual-summary. Summary for unmirrored virtual message.
-
mime-layout. MIME layout information; types, ids, positions, etc of
all MIME entities.
-
mime-encoded-header-flag. Flag that indicates if the headers of the
message are MIME encoded.
-
su-summary-mouse-track-overlay.
-
message-access-method. The access-method to be used for the message,
inherited from its real folder.
-
Attributes. All the hard-wired message attributes are stored in this
vector. They also get saved as part of the
X-VM-v5-Data
header
field when the folder is saved to disk.
-
new-flag. Flag to indicate if the message is “new”.
-
unread-flag. Flag to indicate if the message is unread.
-
deleted-flag. Flag to indicate if the message has been deleted.
-
filed-flag. Flag to indicate if the message has been filed.
-
replied-flag. Flag to indicate if the message has been replied to.
-
written-flag. Flag to indicate if the message has been saved.
-
forwarded-flag. Flag to indicate if the message has been forwarded.
-
edited-flag. Flag to indicate if the message has been edited.
-
redistributed-flag. Flag to indicate if the message has been
redistributed.
-
Cached Data. The data that is cached for the message and stored in the
folder on disk as the
X-VM-v5-Data
header field. Even though
this vector is only supposed to have data that can be calculated from
the message itself, the fields pop-uidl, imap-uid and imap-uid-validity
form an exception. They are really hard data that cannot be calculated
from anything else.
-
byte-count. The size of the message in bytes.
-
weekday, monthday, month, year, hour, zone. Data indicating the date of
the message.
-
full-name. The full name of the author of the message.
-
from. The email address of the author of the message.
-
message-id. The unique id of the message.
-
line-count. The number of lines in the message.
-
subject. The subject string of the message.
-
vheaders-regexp. A regular expression that can be used to find the
start of the already ordered headers.
-
to. Addresses of the recipients of the message in a comma separated
string.
-
to-names. The full names of the recipients in a comma separated string.
Addresses are used if full names are not available.
-
month-number. Numeric month of the sent date.
-
sortable-datestring. Date string of the sent date for sorting purposes.
-
sortable-subject. The subject string for sorting purposes. (Prefixes
such as “re:” are removed.)
-
summary. The summary string for the message.
-
parent. The parent of the message in the message thread, which is
another message data structure.
-
references. Message IDs listed in the References header of the message.
-
headers-to-be-retrieved. Flag that indicates whether the headers of the
message have not been retrieved from the mail server (for POP or IMAP
folders).
-
body-to-be-retrieved. Flag that indicates whether the body of the
message has not been retrieved from the mail server.
-
pop-uidl. The UIDL id of the message on the POP server.
-
imap-uid. The UID of the message on the IMAP server.
-
imap-uid-validity. The UID-VALIDITY value of the message on the IMAP
server.
-
spam-score. The spam score of the message.
-
Mirror Data. Extra data shared by virtual messages if vm-virtual-mirror
is non-nil.
-
edit-buffer. If the message is being edited, this is the buffer being
used.
-
virtual-messages. List of virtual messages mirroring the current real
message.
-
stuff-flag. Flag to indicates if the attribute changes have been
“stuffed” into the folder buffer.
-
labels. List of labels attached to the message.
-
label-string. The string of labels attached to the message.
-
attribute-modflag. Flag to indicate if the attributes of the message
have been modified since the last save.
This document was generated by Build Daemon user on May 13, 2010 using texi2html 1.82.