NNTP support library

Kari Pahula

This is a library for communicating with NNTP (network news transport protocol).

1 NNTP support library

This library handles communication via NNTP.

2 Introduction

2.1 Class Protocol.nntp

This is a subclass of Protocol.protocol. It has the same methods as it's superclass. For method init, port has as its default value 119. It has the following additional methods.

group

group(NameS)

The name of the currently selected newsgroup or nil.

3 Query types

The following queries are available:

3.1 RFC 977 queries

group

group(status  :A 
      name    :+NameS 
      first   :FirstI 
      last    :LastI 
      articles:ArticlesI 
      msg     :MsgS)

Selects group +NameS, returns the first, last and total number of articles if status is ok.

article

article(status  :A 
        selectby:+TypeA 
        num     :NumI 
        id      :IdS 
        head    :HeadR 
        headraw :HeadrawS 
        body    :BodyS 
        msg     :MsgS)

Fetches an article. +TypeA is either num, id or current, which determines which one is used to select the article. Depending on this, +NumI or +IdS may be used as an input for the query. The current article is selected if this is current. Fields head, headraw and body are optional.

head is a record with header lines' names as features and their content as the field. Please see RFC 1036 for a list of header lines.

next

next(status:A 
     msg   :MsgS)

Moves the internal article pointer at the server forward.

last

last(status:A 
     msg   :MsgS)

Moves the internal article pointer at the server backward.

post

post(status :A 
     content:+S 
     msg    :MsgS)

something?

post

post(status :A 
     headraw:+HeadS 
     body   :+BodyS 
     msg    :MsgS)

?

post

post(status:A 
     head  :+HeadR 
     body  :+BodyS 
     msg   :MsgS)

Any of these forms may be used to post an article. In the first form the whole article is in the content field, in the second the article is separated to two strings. The second form will add an empty line after head, per RFC 977.

In the third form the head is a record with line names as features and their content as fields. See RFC 1036 for the required fields. If features 'Date' or 'Message-ID' are missing, they will be added here. 'Message-ID' will be generated from the system clock and file /etc/mailname. (I'll have to come up with something more portable for the latter case, but that should work on GNU/Linux at least.)

Note that all of these will expect the line ends to be LF only and silently convert them to CRLF.

ihave

Identical semantics to post.

quit

quit(status:A 
     msg   :MsgS)

Close the connection.

newgroups

newgroups(status       :A 
          distributions:+DistribL 
          date         :+DateS 
          list               :GroupsL 
          msg               :MsgS)

List of new newsgroups after DateS (format "YYMMDD HHMMSS"). +DistribL is an optional list of distributions. GroupsL is a list of new newsgroups, in similar format to the group query. In addition to the fields the query has, there is a field posting, with value true if posting is allowed to this newsgroup.

Note that the whole query string has to be less than 512. TODO: make a way to check the string length. Until then, excercise care.

newnews

newnews(status       :A 
        newsgroups   :+GroupsL 
        distributions:+DistribL 
        date         :+DateS 
        list             :ArticlesL 
        msg          :MsgS)

List new news after +DateS (format "YYMMDD HHMMSS"). +GroupsL is a comma-separated list of newgroups. +DistribL is a comma-separated list of distribution groups. This field is optional. See RFC 977 for details.

ArticlesL will be a list of articles. They are in the same format as the article query, with field id defined.

Note that the whole query string has to be less than 512. TODO: make a way to check the string length. Until then, excercise care.

3.2 Extension queries

Last section contained queries defined in RFC 977. A number of extensions have been made to that, some of them are implemented here. RFC 2980 has been used as the reference here.

list

list(status:A 
     type  :active
     list  :GroupsL 
     match :+WildS 
     msg   :MsgS)

Same as the list query of RFC 977, with the additional and optional wildcard argument +WildS. Lists newsgroups.

list

list(status:A 
     type  :activetimes
     list  :GroupsL 
     msg   :MsgS)

Lists the groups creation dates and creator emails. List items are of format:created(name:NameS time:TimeI by:EmailS). NameS is the group name, TimeI seconds since the Unix epoch and EmailS the creator's email address.

list

list(status:A 
     type  :distributions
     list  :DistribsL 
     msg   :MsgS)

List valid values for 'Distributions' field in news article headers. List items are of format:distribution:(value:ValS explanation:ExplS). ValS is a value and ExplS is a short explanation for it.

list

list(status:A 
     type  :distribpats
     list  :DistribsL 
     msg   :MsgS)

List valid values for 'Distributions' field in news article headers. List items are of format:distribpat(weight:WeightI name:NameS 
value:ValueS).

list

list(status:A 
     type  :newsgroups
     list  :GroupsL 
     msg   :MsgS)

List newsgroups and short explanations for them. List item's format: group(name:NameS explanation:ExplS).

list

list(status:A 
     type  :overviewfmt
     list  :FieldsL 
     msg   :MsgS)

List of fields in xoverview database. This is called automatically by query xover.

list

list(status:A 
     type  :subscriptionslist
     list  :GroupsL 
     msg   :MsgS)

List of default newsgroups to subscribe to for new users on this server. GroupsL is a list of strings.

xover

xover(status:A 
      num   :+NumI 
      first :+FirstI 
      last  :+LastI 
      list  :ArticlesL 
      msg   :MsgS)

Returns information from the overview database of the specified articles. Article is selected either by +NumI alone, +FirstI alone or with both +FirstI and +LastI. List members' format:article(xover:XOverR). XOverR has the fields listed in self.overviewfmt.

4 Status replies

The status field of queries will have the results of (TODO, read the source for now).

Kari Pahula
Version 1.3.0 (20040430)