[ietf-nntp] LIST HEADERS
Clive D.W. Feather
clive at demon.net
Mon Mar 1 02:34:41 PST 2004
Okay, in the absence of comment pro or anti, I drafted text for a version
of LIST HEADERS that treats both types of HDR command equally.
This is the last item I have outstanding. Once we've resolved it, I can
publish draft 21 and then Russ can decide where we go from here.
Here is the new text with change flags.
8.6 The HDR extension
This extension provides two new commands: HDR and LIST HEADERS. The
label for this extension is HDR.
The HDR extension provides access to specific headers and metadata
items (collectively "fields") of articles or groups of articles. In
the case of headers, an implementation MAY restrict the use of this
extension to a specific list of headers or MAY allow it to be used
- with any header. In the latter case it MUST use the argument "ALL"
- following the extension label in the output of LIST EXTENSIONS; in
- the former case (including the situation where the HDR command may be
- used with any header in some circumstances but only with specific
- headers in others) it MUST NOT use any argument.
+ with any header; it may behave differently when the HDR command is
+ used with a message-id argument and when it is used with a range or
+ no argument. The server MUST use the appropriate argument following
+ the extension label in the output of LIST EXTENSIONS:
+
+ +-----------------+------------+--------------------------+
+ | with message-id | with range | LIST EXTENSIONS argument |
+ +-----------------+------------+--------------------------+
+ | restricted | restricted | (none) |
+ | | | |
+ | restricted | any header | ALLRANGE |
+ | | | |
+ | any header | restricted | ALLMSGID |
+ | | | |
+ | any header | any header | ALL |
+ +-----------------+------------+--------------------------+
The HDR command may take information from a database rather than
directly from the articles. If so, the same issues of consistency and
inconsistency apply as with the OVER extension (Section 8.5) and the
LIST HEADERS command SHOULD take the same approach as the LIST
OVERVIEW.FMT command in resolving them.
[...]
8.6.2 LIST HEADERS
8.6.2.1 Usage
Syntax
! LIST HEADERS [MSGID|RANGE]
Responses
215 Header and metadata list follows (multiline)
Parameters
! MSGID = requests list for access by message-id
! RANGE = requests list for access by range
8.6.2.2 Description
The LIST HEADERS command returns a list of headers and metadata items
that may be retrieved using the HDR command.
The information is returned as a multi-line response following the
215 response code and contains one line for each header or metadata
item name (excluding the colon in the former case). If the
implementation allows any header to be retrieved, it MUST NOT include
any header names in the list but MUST include the special entry ":"
(a single colon on its own); it MUST still list any metadata items
that are available. The order of items in the list is not
significant; the server need not even consistently return the same
order. The list MAY be empty (though in this circumstance there is
little point in providing the extension).
An implementation that also supports the OVER extension SHOULD at
least permit all the headers and metadata items listed in the output
from the LIST OVERVIEW.FMT command.
If the server treats the first form of the HDR command (message-id
specified) differently to the other two forms (range specified or
current article number used) in respect of which headers or metadata
- items are available, then if the optional MSGID argument is
- specified, the results MUST be those items available for the first
- form, while if it is not then they MUST be those available for the
- other two forms. If the server does not treat the first form
- differently, then it MUST produce the same results whether or not the
- optional MSGID argument is specified.
+ items are available, then:
+
+ o if the MSGID argument is specified, the results MUST be those
+ available for the first form of the HDR command;
+
+ o if the RANGE argument is specified, the results MUST be those
+ available for the second and third forms of the HDR command;
+
+ o if no argument is specified, the results MUST be those available
+ in all forms of the HDR command (that is, it MUST only list those
+ items listed in both the previous cases).
+
+ If the server does not treat the various forms differently, then it
+ MUST always produce the same results and ignore any argument.
8.6.2.3 Examples
[...]
Example of an implementation distinguishing the first form of the HDR
command from the other two forms:
[C] LIST EXTENSIONS
[S] 202 extensions supported:
! [S] HDR ALLRANGE
[S] .
! [C] LIST HEADERS RANGE
[S] 215 metadata items supported:
[S] :
[S] :lines
[S] :bytes
[S] .
[C] LIST HEADERS MSGID
[S] 215 headers and metadata items supported:
[S] Date
[S] Distribution
[S] From
[S] Message-ID
[S] References
[S] Subject
[S] :lines
[S] :bytes
+ [S] :x-article-number
[S] .
+ [C] LIST HEADERS
+ [S] 215 headers and metadata items supported:
+ [S] Date
+ [S] Distribution
+ [S] From
+ [S] Message-ID
+ [S] References
+ [S] Subject
+ [S] :lines
+ [S] :bytes
+ [S] .
- Note that LIST EXTENSIONS does not return "HDR ALL" in these
- circumstances.
+ Note how :x-article-number does not appear in the last set of
+ output.
--
Clive D.W. Feather | Work: <clive at demon.net> | Tel: +44 20 8495 6138
Internet Expert | Home: <clive at davros.org> | *** NOTE CHANGE ***
Demon Internet | WWW: http://www.davros.org | Fax: +44 870 051 9937
Thus plc | | Mobile: +44 7973 377646
More information about the ietf-nntp
mailing list