gnus: Back End Interface
11.7.2 Back End Interface
-------------------------
Gnus doesn’t know anything about NNTP, spools, mail or virtual groups.
It only knows how to talk to “virtual servers”. A virtual server is a
“back end” and some “back end variables”. As examples of the first, we
have ‘nntp’, ‘nnspool’ and ‘nnmbox’. As examples of the latter we have
‘nntp-port-number’ and ‘nnmbox-directory’.
When Gnus asks for information from a back end—say ‘nntp’—on
something, it will normally include a virtual server name in the
function parameters. (If not, the back end should use the “current”
virtual server.) For instance, ‘nntp-request-list’ takes a virtual
server as its only (optional) parameter. If this virtual server hasn’t
been opened, the function should fail.
Note that a virtual server name has no relation to some physical
server name. Take this example:
(nntp "odd-one"
(nntp-address "ifi.uio.no")
(nntp-port-number 4324))
Here the virtual server name is ‘odd-one’ while the name of the
physical server is ‘ifi.uio.no’.
The back ends should be able to switch between several virtual
servers. The standard back ends implement this by keeping an alist of
virtual server environments that they pull down/push up when needed.
There are two groups of interface functions: “required functions”,
which must be present, and “optional functions”, which Gnus will always
check for presence before attempting to call ’em.
All these functions are expected to return data in the buffer
‘nntp-server-buffer’ (‘ *nntpd*’), which is somewhat unfortunately
named, but we’ll have to live with it. When I talk about “resulting
data”, I always refer to the data in that buffer. When I talk about
“return value”, I talk about the function value returned by the function
call. Functions that fail should return ‘nil’ as the return value.
Some back ends could be said to be “server-forming” back ends, and
some might be said not to be. The latter are back ends that generally
only operate on one group at a time, and have no concept of “server”;
they have a group, and they deliver info on that group and nothing more.
Gnus identifies each message by way of group name and article number.
A few remarks about these article numbers might be useful. First of
all, the numbers are positive integers. Secondly, it is normally not
possible for later articles to “re-use” older article numbers without
confusing Gnus. That is, if a group has ever contained a message
numbered 42, then no other message may get that number, or Gnus will get
mightily confused.(1) Third, article numbers must be assigned in order
of arrival in the group; this is not necessarily the same as the date of
the message.
The previous paragraph already mentions all the “hard” restrictions
that article numbers must fulfill. But it seems that it might be useful
to assign _consecutive_ article numbers, for Gnus gets quite confused if
there are holes in the article numbering sequence. However, due to the
“no-reuse” restriction, holes cannot be avoided altogether. It’s also
useful for the article numbers to start at 1 to avoid running out of
numbers as long as possible.
Note that by convention, back ends are named ‘nnsomething’, but Gnus
also comes with some ‘nnnotbackends’, such as ‘nnheader.el’, ‘nnmail.el’
and ‘nnoo.el’.
In the examples and definitions I will refer to the imaginary back
end ‘nnchoke’.
Menu