[NNTP] LISTGROUP wording
Clive D.W. Feather
clive at demon.net
Mon Apr 25 09:46:58 PDT 2005
I've edited my master copy to add ranges to LISTGROUP and make the group
argument to GROUP optional. Here's a set of diffs (I've included the
entiretly of 6.1.1 and 6.1.2, then there are two consequental changes
(syntax and summary of response codes).
@@@@@@@@@@@@@@@@@@@@
6.1.1 GROUP
6.1.1.1 Usage
Indicating capability: READER
Syntax
- GROUP group
+ GROUP [group]
Responses
211 number low high group Group successfully selected
411 No such newsgroup
+ 412 No newsgroup selected [1]
Parameters
group = name of newsgroup
number = estimated number of articles in the group
low = reported low water mark
high = reported high water mark
+ [1] The 412 response can only occur if no group has been specified.
+
6.1.1.2 Description
- The required argument is the name of the newsgroup to be selected
- (e.g. "news.software.b"). A list of valid newsgroups may be obtained
- by using the LIST ACTIVE command (see Section 7.6.3).
+ The GROUP command selects a newsgroup as the current selected
+ newsgroup and returns summary information about it.
+
+ The optional argument is the name of the newsgroup to be selected
+ (e.g. "news.software.b"). If no group is specified, the current
+ selected newsgroup is used. A list of valid newsgroups may be
+ obtained by using the LIST ACTIVE command (see Section 7.6.3).
The successful selection response will return the article numbers of
the first and last articles in the group at the moment of selection
(these numbers are referred to as the "reported low water mark" and
the "reported high water mark"), and an estimate of the number of
articles in the group currently available.
If the group is not empty, the estimate MUST be at least the actual
number of articles available, and MUST be no greater than one more
than the difference between the reported low and high water marks.
(Some implementations will actually count the number of articles
currently stored. Others will just subtract the low water mark from
the high water mark and add one to get an estimate.)
If the group is empty, one of the following three situations will
occur. Clients MUST accept all three cases; servers MUST NOT
represent an empty group in any other way.
o The high water mark will be one less than the low water mark, and
the estimated article count will be zero. Servers SHOULD use this
method to show an empty group. This is the only time that the
high water mark can be less than the low water mark.
o All three numbers will be zero.
o The high water mark is greater than or equal to the low water
mark. The estimated article count might be zero or non-zero; if
non-zero, the same requirements apply as for a non-empty group.
The set of articles in a group may change after the GROUP command is
carried out. That is:
o articles may be removed from the group
o articles may be reinstated in the group with the same article
number, but those articles MUST have numbers no less than the
reported low water mark (note that this is a reinstatement of the
previous article, not a new article reusing the number)
o new articles may be added with article numbers greater than the
reported high water mark (if an article that was the one with the
highest number has been removed and the high water mark adjusted
accordingly, the next new article will not have the number one
greater than the reported high water mark)
Except when the group is empty and all three numbers are zero,
whenever a subsequent GROUP command for the same newsgroup is issued,
either by the same client or a different client, the reported low
water mark in the response MUST be no less than that in any previous
response for that newsgroup in any session, and SHOULD be no less
than that in any previous response for that newsgroup ever sent to
any client. Any failure to meet the latter condition SHOULD be
transient only. The client may make use of the low water mark to
remove all remembered information about articles with lower numbers,
as these will never recur. This includes the situation when the high
water mark is one less than the low water mark. No similar
assumption can be made about the high water mark, as this can
decrease if an article is removed, and then increase again if it is
reinstated or if new articles arrive.
When a valid group is selected by means of this command, the current
selected newsgroup MUST be set to that group and the current article
- number MUST be set to the first article in the group. If an empty
- newsgroup is selected, the current article pointer is made invalid.
- If an invalid group is specified, the current selected newsgroup and
- current article number MUST NOT be changed.
+ number MUST be set to the first article in the group (this applies
+ even if the group is already the current selected newsgroup). If an
+ empty newsgroup is selected, the current article pointer is made
+ invalid. If an invalid group is specified, the current selected
+ newsgroup and current article number MUST NOT be changed.
The GROUP or LISTGROUP command (see Section 6.1.2) MUST be used by a
client and a successful response received before any other command is
used that depends on the value of the current selected newsgroup or
current article number.
If the group specified is not available on the server, a 411 response
- MUST be returned.
+ MUST be returned. If no group is specified and the current selected
+ newsgroup is invalid, a 412 response MUST be returned.
+ Note that the ability to omit the group name is a new feature in this
+ specification and servers that do not support CAPABILITIES (and
+ therefore do not conform to this specification) are unlikely to
+ support it.
6.1.1.3 Examples
Example for a group known to the server:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
Example for a group unknown to the server:
[C] GROUP example.is.sob.bradner.or.barber
[S] 411 example.is.sob.bradner.or.barber is unknown
Example of an empty group using the preferred response:
[C] GROUP example.currently.empty.newsgroup
[S] 211 0 4000 3999 example.currently.empty.newsgroup
Example of an empty group using an alternative response:
[C] GROUP example.currently.empty.newsgroup
[S] 211 0 0 0 example.currently.empty.newsgroup
Example of an empty group using a different alternative response:
[C] GROUP example.currently.empty.newsgroup
[S] 211 0 4000 4321 example.currently.empty.newsgroup
+
+ Example reselecting the current selected newsgroup:
+
+ [C] GROUP misc.test
+ [S] 211 1234 234 567 misc.test
+ [C] STAT 444
+ [S] 223 444 <123456 at example.net> retrieved
+ [C] GROUP
+ [S] 211 1234 234 567 misc.test
+ [C] STAT
+ [S] 223 234 <different at example.net> retrieved
+
+ Example of GROUP failing because no group has been selected:
+
+ [Assumes current selected newsgroup is invalid.]
+ [C] GROUP
+ [S] 412 no current group
+ [C] GROUP example.is.sob.bradner.or.barber
+ [S] 411 no such group
+ [C] GROUP
+ [S] 412 no current group
6.1.2 LISTGROUP
6.1.2.1 Usage
Indicating capability: READER with argument LISTGROUP
Syntax
- LISTGROUP [group]
+ LISTGROUP [group [range]]
Responses
211 number low high group Article numbers follow (multi-line)
411 No such newsgroup
412 No newsgroup selected [1]
Parameters
group = name of newsgroup
+ range = range of articles to report
number = estimated number of articles in the group
low = reported low water mark
high = reported high water mark
[1] The 412 response can only occur if no group has been specified.
6.1.2.2 Description
+ The LISTGROUP command selects a newsgroup in the same manner as the
+ the GROUP command (see Section 6.1.1) but also provides a list of
+ article numbers in the newsgroup. Except for the range argument and
+ that the 211 response code is multi-line, its behaviour is identical
+ to the GROUP command.
+
+ On success, a list of article numbers is returned as a multi-line
+ data block following the 211 response code (the arguments on the
+ initial response line are the same as for the GROUP command). The
+ list contains one number per line and is in numerical order. It
+ lists precisely those articles that exist in the group at the moment
+ of selection (therefore an empty group produces an empty list); if
+ the optional range argument is specified, only those articles that
+ are within the range are included in the list (therefore the list MAY
+ be empty even if the group is not).
+
+ The 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
+
+ In the last case, if the second number is less than the first number
+ then the range contains no articles. Omitting the range is
+ equivalent to the range 1- being specified.
+
- The LISTGROUP command is used to get a listing of all the article
- numbers in a particular newsgroup. As a side effect, it also selects
- the group in the same way as the GROUP command (see Section 6.1.1).
-
- The optional argument is the name of the newsgroup to be selected
- (e.g. "news.software.misc"). If no group is specified, the current
- selected newsgroup is used.
-
- On success, the list of article numbers is returned as a multi-line
- data block following the 211 response code (the arguments on the
- initial response line are the same as for the GROUP command). The
- list contains one number per line, is in numerical order, and lists
- precisely those articles that exist in the group at the moment of
- selection (therefore an empty group produces an empty list).
-
- If the group specified is not available on the server, a 411 response
- MUST be returned. If no group is specified and the current selected
- newsgroup is invalid, a 412 response MUST be returned.
-
In all other aspects the LISTGROUP command behaves identically to the
- GROUP command.
+ GROUP command. In particular, when successful, the command sets the
+ current article number to the first article in the group, if any,
+ even if this is not within the range specified by the second
+ argument.
+
+ Note that the range argument (but not, unlike GROUP, the ability to
+ omit the group name) is a new feature in this specification and
+ servers that do not support CAPABILITIES (and therefore do not
+ conform to this specification) are unlikely to support it.
6.1.2.3 Examples
+ Example of LISTGROUP being used to select a group:
+
+ [C] LISTGROUP misc.test
+ [S] 211 2000 3000234 3002322 misc.test list follows
+ [S] 3000234
+ [S] 3000237
+ [S] 3000238
+ [S] 3000239
+ [S] 3002322
+ [S] .
+
Example of LISTGROUP on an empty group:
[C] LISTGROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup list follows
[S] .
Example of LISTGROUP on a valid current selected newsgroup:
[C] GROUP misc.test
[S] 211 2000 3000234 3002322 misc.test
[C] LISTGROUP
[S] 211 2000 3000234 3002322 misc.test list follows
[S] 3000234
[S] 3000237
[S] 3000238
[S] 3000239
[S] 3002322
[S] .
+ Example of LISTGROUP with a range:
+
+ [C] LISTGROUP misc.test 3000238-3000248
+ [S] 211 2000 3000234 3002322 misc.test list follows
+ [S] 3000238
+ [S] 3000239
+ [S] .
+
+ Example of LISTGROUP with an empty range:
+
+ [C] LISTGROUP misc.test 12345678-
+ [S] 211 2000 3000234 3002322 misc.test list follows
+ [S] .
+
+ Example of LISTGROUP with an invalid range:
+
+ [C] LISTGROUP misc.test 9999-111
+ [S] 211 2000 3000234 3002322 misc.test list follows
+ [S] .
+
- Example of LISTGROUP failing because no group has been selected:
-
- [Assumes current selected newsgroup is invalid.]
- [C] LISTGROUP
- [S] 412 no current group
- [C] GROUP example.is.sob.bradner.or.barber
- [S] 411 no such group
- [C] LISTGROUP
- [S] 412 no current group
@@@@@@@@@@@@@@@@@@@@
body-command = "BODY" [WS article-ref]
capabilities-command = "CAPABILITIES" [WS keyword]
date-command = "DATE"
- group-command = "GROUP" WS newsgroup-name
+ group-command = "GROUP" [WS newsgroup-name]
hdr-command = "HDR" WS header-meta-name [WS range-ref]
head-command = "HEAD" [WS article-ref]
help-command = "HELP"
ihave-command = "IHAVE" WS message-id
last-command = "LAST"
list-command = "LIST" [WS list-arguments]
- listgroup-command = "LISTGROUP" [WS newsgroup-name]
+ listgroup-command = "LISTGROUP" [WS newsgroup-name [WS range]]
mode-reader-command = "MODE" WS "READER"
newgroups-command = "NEWGROUPS" WS date-time
newnews-command = "NEWNEWS" WS wildmat WS date-time
@@@@@@@@@@@@@@@@@@@@
Response code 412
- Generated by: ARTICLE, BODY, HDR, HEAD, LAST, LISTGROUP, NEXT,
- OVER, STAT
+ Generated by: ARTICLE, BODY, GROUP, HDR, HEAD, LAST, LISTGROUP,
+ NEXT, OVER, STAT
Meaning: no newsgroup selected.
@@@@@@@@@@@@@@@@@@@@
--
Clive D.W. Feather | Work: <clive at demon.net> | Tel: +44 20 8495 6138
Internet Expert | Home: <clive at davros.org> | Fax: +44 870 051 9937
Demon Internet | WWW: http://www.davros.org | Mobile: +44 7973 377646
Thus plc | |
More information about the ietf-nntp
mailing list