ietf-nntp Re: OVER extension
Clive D.W. Feather
clive at demon.net
Wed Jan 2 02:01:54 PST 2002
My proposed new text.
Note that change marks are *not* included. Some possible variations are
noted by ? in the left margin. These are:
(1) Allow (but don't require) a server to treat lone LF as CRLF.
(2) In LIST OVERVIEW.FMT, choose between "Bytes:", "Bytes", or either
with the latter preferred [and ditto "Lines".]
(3) Remove a paragraph I think is unnecessary.
There was a suggestion that OVER could take a message-ID. This would need
to be optional; to allow it, include the lines prefixed with $, while to
forbid it exclude those lines.
9.5.2 The OVER Extension
This extension provides two commands, OVER and LIST OVERVIEW.FMT. The
label for this extension is OVER. If the extension is implemented then
both commands MUST be provided.
The OVER extension provides access to a database of header lines
extracted from incoming articles. Only certain headers are included
in the database.
9.5.2.1 OVER
OVER [range]
$ OVER <message-id>
The OVER command returns the contents of the headers in the database
for the article(s) specified from the current selected group.
The optional range argument may be any of the following:
o an article number
o an article number followed by a dash to indicate all
following
o an article number followed by a dash followed by another
article number
If no argument is specified, then information from the current article
is displayed. Successful responses start with a 224 response followed
by the overview information for all matched messages. This is a multiline
response with one line per article. A 412 error response is returned if
no newsgroup is currently selected. A 420 error response is returned if
there are no articles in the indicated range.
For a successful response, the returned information consists of one line
per article, sorted in numerical order of article number. Each line
consists of a number of fields separated by an US-ASCII TAB character.
A field may be empty (in which case there will be two adjacent US-ASCII
tabs), and a sequence of trailing US-ASCII tabs may be omitted.
The first 8 fields MUST be the following, in order:
article number
"Subject" header
"From" header
"Date" header
"Message-ID" header
"References" header
byte count
line count
Any subsequent fields are the contents of the other headers held in the
database. The headers MUST be returned in the order specified by the
LIST OVERVIEW.FMT command.
The byte count and line count MUST be decimal integers. They MUST
count the entire article, both header and body. The line count is
the number of US-ASCII CRLF pairs, each of which counts as two bytes.
These values MUST be returned; the corresponding fields MUST NOT be
empty.
For the five mandatory headers, the content of each field MUST be based
on the original header with the header name and following colon and
space removed. For all subsequent fields the content MUST be based on
the entire header, including the name. In every case, the header is
processed by first removing all US-ASCII CRLF pairs and then replacing
each remaining US-ASCII NUL, TAB, CR, or LF character with a single
US-ASCII space (for example, CR LF LF TAB will become two spaces).
[Possible addition]
? Alternatively, a server MAY treat a lone LF - both here and in the line
? count - as if it were CRLF.
$ A server MAY, but is not required to, support the second form of the
$ command, specifying a message-ID. If it does, no newsgroup need be
$ selected and the article number in the output is replaced by "0".
The server SHOULD NOT produce output for articles that no longer
exist.
9.5.2.1.1 Responses
$ First form (optional range specified):
224 Overview information follows (multi-line response)
412 No newsgroup currently selected
420 No article(s) selected
plus generic responses 400, 401, 403, 500, 501, 502, 503
$ Second form (message-ID specified):
$
$ 224 Overview information follows (multi-line response)
$ 430 No article found with that message-id
$
$ plus generic responses 400, 401, 403, 500, 501, 502, 503
9.5.2.1.2 Examples
Please note that, in these examples, US-ASCII tab has been replaced
by vertical bar and that some lines have been folded for readability
(shown by ++ in the left margin).
Example of a successful retrieval of overview information for an
article (using no article number)
[S] 200 NNTP Service Ready
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] OVER
[S] 224 Overview information follows
[S] 3000234|I am just a test article|nobody at nowhere.to
++ (Demo User)|6 Oct 1998 04:38:40 -0500|<45223423 at to.to>||
++ 4822|37|X-NNTP-Posting-Host: user.nowhere.to
[S] .
Example of a successful retrieval of overview information for a
range of articles
[S] 200 NNTP Service Ready
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] OVER 3000234-3000240
[S] 224 Overview information follows
[S] 3000234|I am just a test article|nobody at nowhere.to
++ (Demo User)|6 Oct 1998 04:38:40 -0500|<45223423 at to.to>||
++ 4822|37|X-NNTP-Posting-Host: user.nowhere.to
[S] 3000235|Another test article|nobody at nowhere.to
++ (Demo User)|6 Oct 1998 04:38:45 -0500|<45223425 at to.to>||
++ 4818|37|X-NNTP-Posting-Host: user.nowhere.to
[S] 3000238|Re: I am just a test article|somebody at elsewhere.to|
++ 7 Oct 1998 11:38:40 +1200|<kfwer3v at elsewhere.to>|
++ <45223423 at to.to>|9234|51
[S] .
Note the missing "References" header in the first two lines, the
missing trailing field in the last line, and that there are only
results for those articles that still exist.
$ Example of a successful retrieval of overview information for an
$ article (using the message-ID)
$
$ [S] 200 NNTP Service Ready
$ [C] OVER <45223423 at to.to>
$ [S] 224 Overview information follows
$ [S] 0|I am just a test article|nobody at nowhere.to (Demo User)|
$ ++ 6 Oct 1998 04:38:40 -0500|<45223423 at to.to>||4822|37|
$ ++ X-NNTP-Posting-Host: user.nowhere.to
$ [S] .
Example of an unsuccessful retrieval of overview information on an
article by number
[S] 200 NNTP Service Ready
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] OVER 300256
[S] 420 No such article in this group
Example of an unsuccessful retrieval of overview information by number
because no newsgroup was selected first
[S] 200 NNTP Service Ready
[C] OVER
[S] 412 No newsgroup selected
Example of an attempt to retrieve an article when the current group
selected is empty
[S] 200 NNTP Service Ready
[C] GROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup
[C] OVER
[S] 420 No current article selected
9.5.2.2 LIST OVERVIEW.FMT
LIST OVERVIEW.FMT
The LIST OVERVIEW.FMT command returns a description of the fields in
the database, in the order that the OVER command returns them.
If the command is successful, the description is returned as a multi-line
response following a 215 response code, one line per field. The first 7
lines MUST be exactly:
Subject:
From:
Date:
Message-ID:
References:
[For backwards compatibility, the next two lines are:]
? Bytes:
? Lines:
[I recommend we change them to be:]
? Bytes
? Lines
[In the latter case, we could add the text:]
? except that the last two lines MAY, but SHOULD NOT, have a colon at the
? end.
All subsequent lines MUST consist of a header name followed by ":full".
There are no leading or trailing spaces in the output.
Note: the 7 fixed lines describe the 2nd to 8th fields of the OVER
output. The last two of these must be accurate byte and line counts
which, despite the names used here, are not related to any "Bytes" or
"Lines" headers in the article. The "full" suffix is a reminder that
the corresponding fields include the header name.
This command MUST generate the same results throughout a session.
[Query: is the following paragraph needed, since this is a generic code.]
? If the information is not available, the server MUST return the 503
? response.
9.5.2.2.1 Responses
215 Information follows (multi-line response)
plus generic responses 400, 401, 403, 501, 502, 503
9.5.2.2.2 Examples
Example of LIST OVERVIEW.FMT output corresponding to the example
OVER output above:
[S] 200 NNTP Service Ready
[C] LIST OVERVIEW.FMT
[S] 215 Order of fields in overview database.
[S] Subject:
[S] From:
[S] Date:
[S] Message-ID:
[S] References:
[S] Bytes:
[S] Lines:
[S] X-NNTP-Posting-Host:full
[S] .
--
Clive D.W. Feather | Work: <clive at demon.net> | Tel: +44 20 8371 1138
Internet Expert | Home: <clive at davros.org> | Fax: +44 20 8371 4037
Demon Internet | WWW: http://www.davros.org | Mobile: +44 7973 377646
Thus plc | |
More information about the ietf-nntp
mailing list