ietf-nntp Current HDR text
Russ Allbery
rra at stanford.edu
Sun Aug 25 22:30:48 PDT 2002
This is the current HDR text, reordered so that it matches the current
ordering of command descriptions in our draft. I think it's suitable for
inclusion; we can always iron out additional modifications later.
I haven't included any notes about metadata yet; see my other message.
I changed the description from the previous description to return article
numbers but no data for articles which are present but do not have the
header in question. This is consistent with the existing behavior of XHDR
as pointed out by Andrew. Unless there is a strong argument for breaking
with that tradition, I think it's best to stick with existing practice.
But I can be convinced otherwise.
I still also have the text with the other ordering, which I find somewhat
clearer.
9.5.3 The HDR Extension
This extension provides one new command, HDR. The label for this
extension is HDR.
9.5.3.1 HDR
HDR header
HDR header range
HDR header <message-id>
The HDR command retrieves specific headers from a specified range of
articles in the currently selected group or an article specified by
message-id.
The required header parameter is the name of a header (e.g. "subject")
in an article and is case-insensitive. The range parameter of the
second form of the HDR command may be any of the following:
* an article number
* an article number followed by a dash to indicate all following
* an article number followed by a dash followed by another article
number.
The message-id parameter of the third form of the HDR command indicates
a specific article. The range and message-id arguments are mutually
exclusive. If neither are specified, information from the current
article is displayed.
A successful response consists of a 225 response followed by the
requested list of headers. This list is returned as a multiline
response, with each line consisting of the article number, a US-ASCII
space, and the contents of the header (without the header name or the
colon and space that follow it). The header contents are modified as
follows: all US-ASCII CRLF pairs are removed, and then each remaining
US-ASCII NUL, TAB, CR, or LF character is replaced with a single
US-ASCII space. (Note that this is the same transformation as is
performed by the OVER extension.)
The header content is in all cases taken from the article. This means
that, for example, a request for the header "Lines" returns the contents
of the "Lines" header of the specified articles, not the Lines field
returned by the OVER extension or any other server-generated value.
If the header occurs in a given article multiple times, only the value
of the first occurrence is returned by HDR.
If the article is specified by message-id rather than by article range,
the article number is given as "0". If the requested header is not
present in the article or if it is present but empty, a line for that
article is included in the output but the header content portion of the
line is empty. If any article number in the provided range does not
exist in the group, no line for that article number is included in the
output.
If the optional argument is a message-id and no such article exists, a
430 error response shall be returned. If the optional argument is an
article number or number range and no article with that number or in
that number range exists in the current group, a 423 error response
shall be returned. If HDR is sent without any arguments and no article
is currently selected, a 420 error response shall be returned.
A server MAY only allow HDR commands for a limited set of headers (such
as those present in the overview database). If it does so, it MUST
respond with a 503 error response to attempts to request other headers
rather than returning erroneous results such as a successful empty
response.
9.5.3.1.1 Responses
225 Headers follow (multiline response)
412 No newsgroup selected
420 No article selected
423 No article with that number
430 No article with that message ID
9.5.3.1.2 Examples
Example of a successful retrieval of subject lines from a range of
articles (3000235 has no Subject header, and 3000236 is missing):
[S] 200 NNTP Service Ready
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR Subject 3000234-300238
[S] 225 Headers follow
[S] 3000234 I am just a test article
[S] 3000235
[S] 3000237 Re: I am just a test article
[S] 3000238 Ditto
[S] .
Example of a successful retrieval of the subject line from an article by
message-id:
[S] 200 NNTP Service Ready
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR subject <i.am.a.test.article at example.com>
[S] 225 Header information follows
[S] 0 I am just a test article
[S] .
Example of a successful retrieval of the subject line from the current
article:
[S] 200 NNTP Service Ready
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR subject
[S] 225 Header information follows
[S] 3000234 I am just a test article
[S] .
Example of an unsuccessful retrieval of a header from an article by
message-id:
[S] 200 NNTP Service Ready
[C] HDR subject <i.am.not.there at example.com>
[S] 430 No Such Article Found
Example of an unsuccessful retrieval of headers from articles by number
because no newsgroup was selected first:
[S] 200 NNTP Service Ready
[C] HDR subject 300256-
[S] 412 No newsgroup selected
Example of an unsuccessful retrieval of headers because the current
group is empty:
[S] 200 NNTP Service Ready
[C] GROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup
[C] HDR subject 1-
[S] 423 No articles in that range
[S] .
Example of an unsuccessful retrieval of headers because the server does
not allow HDR commands for that header:
[S] 200 NNTP Service Ready
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR Content-Type 3000234-300238
[S] 503 HDR not permitted on "Content-Type"
Example of a failure due to restrictions configured into the server:
[S] 200 NNTP Service Ready
[C] GROUP news.group
[S] 211 1234 3000234 3002322 misc.test
[C] HDR Subject 3000234-300238
[S] 502 Service Unavailable
--
Russ Allbery (rra at stanford.edu) <http://www.eyrie.org/~eagle/>
More information about the ietf-nntp
mailing list