gnus: Optional Back End Functions
11.7.2.2 Optional Back End Functions
....................................
‘(nnchoke-retrieve-groups GROUPS &optional SERVER)’
GROUPS is a list of groups, and this function should request data
on all those groups. How it does it is of no concern to Gnus, but
it should attempt to do this in a speedy fashion.
The return value of this function can be either ‘active’ or
‘group’, which says what the format of the result data is. The
former is in the same format as the data from
‘nnchoke-request-list’, while the latter is a buffer full of lines
in the same format as ‘nnchoke-request-group’ gives.
group-buffer = *active-line / *group-status
‘(nnchoke-request-update-info GROUP INFO &optional SERVER)’
A Gnus group info (
Group Info) is handed to the back end
for alterations. This comes in handy if the back end really
carries all the information (as is the case with virtual and imap
groups). This function should destructively alter the info to suit
its needs, and should return a non-‘nil’ value (exceptionally,
‘nntp-request-update-info’ always returns ‘nil’ not to waste the
network resources).
There should be no result data from this function.
‘(nnchoke-request-type GROUP &optional ARTICLE)’
When the user issues commands for “sending news” (‘F’ in the
summary buffer, for instance), Gnus has to know whether the article
the user is following up on is news or mail. This function should
return ‘news’ if ARTICLE in GROUP is news, ‘mail’ if it is mail and
‘unknown’ if the type can’t be decided. (The ARTICLE parameter is
necessary in ‘nnvirtual’ groups which might very well combine mail
groups and news groups.) Both GROUP and ARTICLE may be ‘nil’.
There should be no result data from this function.
‘(nnchoke-request-set-mark GROUP ACTION &optional SERVER)’
Set/remove/add marks on articles. Normally Gnus handles the
article marks (such as read, ticked, expired etc.) internally, and
store them in ‘~/.newsrc.eld’. Some back ends (such as IMAP)
however carry all information about the articles on the server, so
Gnus need to propagate the mark information to the server.
ACTION is a list of mark setting requests, having this format:
(RANGE ACTION MARK)
RANGE is a range of articles you wish to update marks on. ACTION
is ‘add’ or ‘del’, used to add marks or remove marks (preserving
all marks not mentioned). MARK is a list of marks; where each mark
is a symbol. Currently used marks are ‘read’, ‘tick’, ‘reply’,
‘expire’, ‘killed’, ‘dormant’, ‘save’, ‘download’, ‘unsend’, and
‘forward’, but your back end should, if possible, not limit itself
to these.
Given contradictory actions, the last action in the list should be
the effective one. That is, if your action contains a request to
add the ‘tick’ mark on article 1 and, later in the list, a request
to remove the mark on the same article, the mark should in fact be
removed.
An example action list:
(((5 12 30) 'del '(tick))
((10 . 90) 'add '(read expire))
((92 94) 'del '(read)))
The function should return a range of articles it wasn’t able to
set the mark on (currently not used for anything).
There should be no result data from this function.
‘(nnchoke-request-update-mark GROUP ARTICLE MARK)’
If the user tries to set a mark that the back end doesn’t like,
this function may change the mark. Gnus will use whatever this
function returns as the mark for ARTICLE instead of the original
MARK. If the back end doesn’t care, it must return the original
MARK, and not ‘nil’ or any other type of garbage.
The only use for this I can see is what ‘nnvirtual’ does with it—if
a component group is auto-expirable, marking an article as read in
the virtual group should result in the article being marked as
expirable.
There should be no result data from this function.
‘(nnchoke-request-scan &optional GROUP SERVER)’
This function may be called at any time (by Gnus or anything else)
to request that the back end check for incoming articles, in one
way or another. A mail back end will typically read the spool file
or query the POP server when this function is invoked. The GROUP
doesn’t have to be heeded—if the back end decides that it is too
much work just scanning for a single group, it may do a total scan
of all groups. It would be nice, however, to keep things local if
that’s practical.
There should be no result data from this function.
‘(nnchoke-request-group-description GROUP &optional SERVER)’
The result data from this function should be a description of
GROUP.
description-line = name <TAB> description eol
name = <string>
description = <text>
‘(nnchoke-request-list-newsgroups &optional SERVER)’
The result data from this function should be the description of all
groups available on the server.
description-buffer = *description-line
‘(nnchoke-request-newgroups DATE &optional SERVER)’
The result data from this function should be all groups that were
created after ‘date’, which is in normal human-readable date format
(i.e., the date format used in mail and news headers, and returned
by the function ‘message-make-date’ by default). The data should
be in the active buffer format.
It is okay for this function to return “too many” groups; some back
ends might find it cheaper to return the full list of groups,
rather than just the new groups. But don’t do this for back ends
with many groups. Normally, if the user creates the groups
herself, there won’t be too many groups, so ‘nnml’ and the like are
probably safe. But for back ends like ‘nntp’, where the groups
have been created by the server, it is quite likely that there can
be many groups.
‘(nnchoke-request-create-group GROUP &optional SERVER)’
This function should create an empty group with name GROUP.
There should be no return data.
‘(nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)’
This function should run the expiry process on all articles in the
ARTICLES range (which is currently a simple list of article
numbers.) It is left up to the back end to decide how old articles
should be before they are removed by this function. If FORCE is
non-‘nil’, all ARTICLES should be deleted, no matter how new they
are.
This function should return a list of articles that it did not/was
not able to delete.
There should be no result data returned.
‘(nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM &optional LAST)’
This function should move ARTICLE (which is a number) from GROUP by
calling ACCEPT-FORM.
This function should ready the article in question for moving by
removing any header lines it has added to the article, and
generally should “tidy up” the article. Then it should ‘eval’
ACCEPT-FORM in the buffer where the “tidy” article is. This will
do the actual copying. If this ‘eval’ returns a non-‘nil’ value,
the article should be removed.
If LAST is ‘nil’, that means that there is a high likelihood that
there will be more requests issued shortly, so that allows some
optimizations.
The function should return a cons where the ‘car’ is the group name
and the ‘cdr’ is the article number that the article was entered
as.
There should be no data returned.
‘(nnchoke-request-accept-article GROUP &optional SERVER LAST)’
This function takes the current buffer and inserts it into GROUP.
If LAST in ‘nil’, that means that there will be more calls to this
function in short order.
The function should return a cons where the ‘car’ is the group name
and the ‘cdr’ is the article number that the article was entered
as.
The group should exist before the back end is asked to accept the
article for that group.
There should be no data returned.
‘(nnchoke-request-replace-article ARTICLE GROUP BUFFER)’
This function should remove ARTICLE (which is a number) from GROUP
and insert BUFFER there instead.
There should be no data returned.
‘(nnchoke-request-delete-group GROUP FORCE &optional SERVER)’
This function should delete GROUP. If FORCE, it should really
delete all the articles in the group, and then delete the group
itself. (If there is such a thing as “the group itself”.)
There should be no data returned.
‘(nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)’
This function should rename GROUP into NEW-NAME. All articles in
GROUP should move to NEW-NAME.
There should be no data returned.
Info Catalog
gnus: Required Back End Functions
gnus: Back End Interface
gnus: Error Messaging