Next: Optional Back End Functions, Up: Back End Interface [Contents][Index]

#### 11.7.2.1 Required Back End Functions

`(nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)`

  articles is either a range of article numbers or a list of `Message-ID`s. Current back ends do not fully support either—only sequences (lists) of article numbers, and most back ends do not support retrieval of `Message-ID`s. But they should try for both.

  The result data should either be HEADs or NOV lines, and the result value should either be `headers` or `nov` to reflect this. This might later be expanded to `various`, which will be a mixture of HEADs and NOV lines, but this is currently not supported by Gnus.

  If fetch-old is non-`nil` it says to try fetching “extra headers”, in some meaning of the word. This is generally done by fetching (at most) fetch-old extra headers less than the smallest article number in `articles`, and filling the gaps as well. The presence of this parameter can be ignored if the back end finds it cumbersome to follow the request. If this is non-`nil` and not a number, do maximum fetches.

  Here’s an example HEAD:

      221 1056 Article retrieved.
      Path: ifi.uio.no!sturles
      From: sturles@ifi.uio.no (Sturle Sunde)
      Newsgroups: ifi.discussion
      Subject: Re: Something very droll
      Date: 27 Oct 1994 14:02:57 +0100
      Organization: Dept. of Informatics, University of Oslo, Norway
      Lines: 26
      Message-ID: <38o8e1$a0o@holmenkollen.ifi.uio.no>
      References: <38jdmq$4qu@visbur.ifi.uio.no>
      NNTP-Posting-Host: holmenkollen.ifi.uio.no
      .

  So a `headers` return value would imply that there’s a number of these in the data buffer.

  Here’s a BNF definition of such a buffer:

      headers        = *head
      head           = error / valid-head
      error-message  = [ "4" / "5" ] 2number " " <error message> eol
      valid-head     = valid-message *header "." eol
      valid-message  = "221 " <number> " Article retrieved." eol
      header         = <text> eol

  (The version of BNF used here is the one used in RFC822.)

  If the return value is `nov`, the data buffer should contain network overview database lines. These are basically fields separated by tabs.

      nov-buffer = *nov-line
      nov-line   = field 7*8[ <TAB> field ] eol
      field      = <text except TAB>

  For a closer look at what should be in those fields, see Headers.

`(nnchoke-open-server SERVER &optional DEFINITIONS)`

  server is here the virtual server name. definitions is a list of `(VARIABLE VALUE)` pairs that define this virtual server.

  If the server can’t be opened, no error should be signaled. The back end may then choose to refuse further attempts at connecting to this server. In fact, it should do so.

  If the server is opened already, this function should return a non-`nil` value. There should be no data returned.

`(nnchoke-close-server &optional SERVER)`

  Close connection to server and free all resources connected to it. Return `nil` if the server couldn’t be closed for some reason.

  There should be no data returned.

`(nnchoke-request-close)`

  Close connection to all servers and free all resources that the back end have reserved. All buffers that have been created by that back end should be killed. (Not the `nntp-server-buffer`, though.) This function is generally only called when Gnus is shutting down.

  There should be no data returned.

`(nnchoke-server-opened &optional SERVER)`

  If server is the current virtual server, and the connection to the physical server is alive, then this function should return a non-`nil` value. This function should under no circumstances attempt to reconnect to a server we have lost connection to.

  There should be no data returned.

`(nnchoke-status-message &optional SERVER)`

  This function should return the last error message from server.

  There should be no data returned.

`(nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)`

  The result data from this function should be the article specified by article. This might either be a `Message-ID` or a number. It is optional whether to implement retrieval by `Message-ID`, but it would be nice if that were possible.

  If to-buffer is non-`nil`, the result data should be returned in this buffer instead of the normal data buffer. This is to make it possible to avoid copying large amounts of data from one buffer to another, while Gnus mainly requests articles to be inserted directly into its article buffer.

  If it is at all possible, this function should return a cons cell where the `car` is the group name the article was fetched from, and the `cdr` is the article number. This will enable Gnus to find out what the real group and article numbers are when fetching articles by `Message-ID`. If this isn’t possible, `t` should be returned on successful article retrieval.

`(nnchoke-request-group GROUP &optional SERVER FAST INFO)`

  Get data on group. This function also has the side effect of making group the current group.

  If fast, don’t bother to return useful data, just make group the current group.

  If info, it allows the backend to update the group info structure.

  Here’s an example of some result data and a definition of the same:

      211 56 1000 1059 ifi.discussion

  The first number is the status, which should be 211. Next is the total number of articles in the group, the lowest article number, the highest article number, and finally the group name. Note that the total number of articles may be less than one might think while just considering the highest and lowest article numbers, but some articles may have been canceled. Gnus just discards the total-number, so whether one should take the bother to generate it properly (if that is a problem) is left as an exercise to the reader. If the group contains no articles, the lowest article number should be reported as 1 and the highest as 0.

      group-status = [ error / info ] eol
      error        = [ "4" / "5" ] 2<number> " " <Error message>
      info         = "211 " 3* [ <number> " " ] <string>

`(nnchoke-close-group GROUP &optional SERVER)`

  Close group and free any resources connected to it. This will be a no-op on most back ends.

  There should be no data returned.

`(nnchoke-request-list &optional SERVER)`

  Return a list of all groups available on server. And that means all.

  Here’s an example from a server that only carries two groups:

      ifi.test 0000002200 0000002000 y
      ifi.discussion 3324 3300 n

  On each line we have a group name, then the highest article number in that group, the lowest article number, and finally a flag. If the group contains no articles, the lowest article number should be reported as 1 and the highest as 0.

      active-file = *active-line
      active-line = name " " <number> " " <number> " " flags eol
      name        = <string>
      flags       = "n" / "y" / "m" / "x" / "j" / "=" name

  The flag says whether the group is read-only (‘`n`’), is moderated (‘`m`’), is dead (‘`x`’), is aliased to some other group (‘`=other-group`’) or none of the above (‘`y`’).

`(nnchoke-request-post &optional SERVER)`

  This function should post the current buffer. It might return whether the posting was successful or not, but that’s not required. If, for instance, the posting is done asynchronously, it has generally not been completed by the time this function concludes. In that case, this function should set up some kind of sentinel to beep the user loud and clear if the posting could not be completed.

  There should be no result data from this function.

Next: Optional Back End Functions, Up: Back End Interface [Contents][Index]