


nntp(n)              Tcl NNTP Client Library              nntp(n)


______________________________________________________________________________

NAME
       nntp - Tcl client for the NNTP protocol

SYNOPSIS
       package require Tcl  8.2

       package require nntp  ?0.2.1?

       ::nntp::nntp ?host? ?port? ?nntpName?

       nntpName method ?arg arg ...?

       nntpName article ?msgid?

       nntpName authinfo ?user? ?pass?

       nntpName body ?msgid?

       nntpName configure

       nntpName configure option

       nntpName configure option value ...

       nntpName cget option

       nntpName date

       nntpName group ?group?

       nntpName head ?msgid?

       nntpName help

       nntpName last

       nntpName list

       nntpName listgroup ?group?

       nntpName mode_reader

       nntpName newgroups since

       nntpName newnews

       nntpName newnews since

       nntpName newnews group ?since?

       nntpName next




nntp                          1.5.1                             1





nntp(n)              Tcl NNTP Client Library              nntp(n)


       nntpName post article

       nntpName slave

       nntpName stat ?msgid?

       nntpName quit

       nntpName xgtitle ?group_pattern?

       nntpName xhdr field ?range?

       nntpName xover ?range?

       nntpName xpat field range ?pattern_list?

_________________________________________________________________

DESCRIPTION
       The package nntp provides a simple Tcl-only client library for the NNTP
       protocol.  It works by opening the standard NNTP socket on the  server,
       and then providing a Tcl API to access the NNTP protocol commands.  All
       server errors are returned as Tcl errors (thrown) which must be  caught
       with the Tcl catch command.

COMMANDS
       ::nntp::nntp ?host? ?port? ?nntpName?
              The  command  opens  a  socket  connection to the specified NNTP
              server and creates a new nntp object with an  associated  global
              Tcl  command whose name is nntpName. This command may be used to
              access the various NNTP protocol commands for  the  new  connec-
              tion.  The  default port number is "119" and the default host is
              "news". These defaults can be overridden  with  the  environment
              variables NNTPPORT and NNTPHOST respectively.

              Some  of  the commands supported by this package are not part of
              the nntp rfc 977 (http://www.rfc-editor.org/rfc/rfc977.txt)  and
              will not be available (or implemented) on all nntp servers.

              The access command nntpName has the following general form:

              nntpName method ?arg arg ...?
                     Option  and  the args determine the exact behavior of the
                     command.

       nntpName article ?msgid?
              Query the server for article msgid from the current group.   The
              article is returned as a valid tcl list which contains the head-
              ers, followed by a blank line, and then followed by the body  of
              the  article.  Each element in the list is one line of the arti-
              cle.

       nntpName authinfo ?user? ?pass?
              Send authentication information (username and password)  to  the



nntp                          1.5.1                             2





nntp(n)              Tcl NNTP Client Library              nntp(n)


              server.

       nntpName body ?msgid?
              Query the server for the body of the article msgid from the cur-
              rent group.  The body of the article is returned as a valid  tcl
              list.  Each  element  in the list is one line of the body of the
              article.

       nntpName configure

       nntpName configure option

       nntpName configure option value ...

       nntpName cget option
              Query and configure options of the nntp connection object.  Cur-
              rently  only one option is supported, -binary. When set articles
              are retrieved as binary data instead of text. The  only  methods
              affected by this are article and body.

              One application of this option would be the download of articles
              containing yEnc encoded images. Although  encoded  the  data  is
              still  mostly  binary and retrieving it as text will corrupt the
              information.

              See package yencode for both encoder and decoder of such data.

       nntpName date
              Query the server for the servers  current  date.   The  date  is
              returned in the format YYYYMMDDHHMMSS.

       nntpName group ?group?
              Optionally set the current group, and retrieve information about
              the currently selected group.  Returns the estimated  number  of
              articles  in the group followed by the number of the first arti-
              cle in the group, followed by the last  article  in  the  group,
              followed by the name of the group.

       nntpName head ?msgid?
              Query  the  server for the headers of the article msgid from the
              current group.  The headers of the article  are  returned  as  a
              valid  tcl  list.  Each  element  in the list is one line of the
              headers of the article.

       nntpName help
              Retrieves a list of the commands that are supported by the  news
              server that is currently attached to.

       nntpName last
              Sets  the  current article pointer to point to the previous mes-
              sage (if there is one) and returns the msgid of that message.

       nntpName list
              Returns  a  tcl  list  of  valid   newsgroups   and   associated



nntp                          1.5.1                             3





nntp(n)              Tcl NNTP Client Library              nntp(n)


              information.   Each  newsgroup  is returned as an element in the
              tcl list with the following format:

                    group last first p

              where <group> is the name of the newsgroup, <last> is the number
              of  the  last known article currently in that newsgroup, <first>
              is the number of the first article currently in  the  newsgroup,
              and  <p> is either 'y' or 'n' indicating whether posting to this
              newsgroup is allowed ('y') or prohibited ('n').

              The <first> and <last> fields will always be numeric.  They  may
              have  leading zeros.  If the <last> field evaluates to less than
              the <first> field, there are no articles currently  on  file  in
              the newsgroup.

       nntpName listgroup ?group?
              Query  the  server  for a list of all the messages (message num-
              bers) in the group specified by the argument  group  or  by  the
              current group if the group argument was not passed.

       nntpName mode_reader
              Query the server for its nntp 'MODE READER' response string.

       nntpName newgroups since
              Query  the  server  for a list of all the new newsgroups created
              since the time specified by the argument  since.   The  argument
              since  can  be any time string that is understood by clock scan.
              The tcl list of newsgroups is returned in a similar form to  the
              list of groups returned by the nntpName list command.  Each ele-
              ment of the list has the form:

                    group last first p

              where <group> is the name of the newsgroup, <last> is the number
              of  the  last known article currently in that newsgroup, <first>
              is the number of the first article currently in  the  newsgroup,
              and  <p> is either 'y' or 'n' indicating whether posting to this
              newsgroup is allowed ('y') or prohibited ('n').

       nntpName newnews
              Query the server for a list of new articles posted to  the  cur-
              rent group in the last day.

       nntpName newnews since
              Query  the  server for a list of new articles posted to the cur-
              rent group since the time specified by the argument since.   The
              argument  since  can  be  any  time string that is understood by
              clock scan.

       nntpName newnews group ?since?
              Query the server for a list of new articles posted to the  group
              specified  by the argument group since the time specified by the
              argument since (or in the past  day  if  no  since  argument  is



nntp                          1.5.1                             4





nntp(n)              Tcl NNTP Client Library              nntp(n)


              passed.   The  argument  since  can  be  any time string that is
              understood by clock scan.

       nntpName next
              Sets the current article pointer to point to  the  next  message
              (if there is one) and returns the msgid of that message.

       nntpName post article
              Posts   an   article   of   the   form  specified  in  RFC  1036
              (http://www.rfc-editor.org/rfc/rfc1036.txt,  successor  to   RFC
              850) to the current news group.

       nntpName slave
              Identifies  a connection as being made from a slave nntp server.
              This might be used to indicate that the  connection  is  serving
              multiple  people  and  should  be given priority.  Actual use is
              entirely implementation dependent and may vary  from  server  to
              server.

       nntpName stat ?msgid?
              The  stat  command is similar to the article command except that
              no text is returned.  When selecting by message number within  a
              group,  the  stat  command  serves  to  set  the current article
              pointer  without  sending  text.  The  returned   acknowledgment
              response  will  contain  the  message-id,  which  may be of some
              value.  Using the stat command to select by message-id is  valid
              but  of questionable value, since a selection by message-id does
              NOT alter the "current article pointer"

       nntpName quit
              Gracefully close the connection after sending a NNTP  QUIT  com-
              mand down the socket.

       nntpName xgtitle ?group_pattern?
              Returns a tcl list where each element is of the form:

              newsgroup description

              If  a group_pattern is specified then only newsgroups that match
              the pattern will have their name and description returned.

       nntpName xhdr field ?range?
              Returns the specified header field value for the current message
              or  for a list of messages from the current group.  field is the
              title of a field in the header such as from, subject, date, etc.
              If  range  is not specified or is "" then the current message is
              queried.  The command returns a list of elements where each ele-
              ment has the form of:

                  msgid value

              Where  msgid is the number of the message and value is the value
              set for the queried field.  The range argument can be in any  of
              the following forms:



nntp                          1.5.1                             5





nntp(n)              Tcl NNTP Client Library              nntp(n)


              ""     The current message is queried.

              msgid1-msgid2
                     All  messages between msgid1 and msgid2 (including msgid1
                     and msgid2) are queried.

              msgid1 msgid2
                     All messages between msgid1 and msgid2 (including  msgid1
                     and msgid2) are queried.

       nntpName xover ?range?
              Returns  header  information  for  the  current message or for a
              range of messages from the current group.   The  information  is
              returned in a tcl list where each element is of the form:

                  msgid subject from date idstring bodysize headersize xref

              If  range  is not specified or is "" then the current message is
              queried.  The range argument can be  in  any  of  the  following
              forms:

              ""     The current message is queried.

              msgid1-msgid2
                     All  messages between msgid1 and msgid2 (including msgid1
                     and msgid2) are queried.

              msgid1 msgid2
                     All messages between msgid1 and msgid2 (including  msgid1
                     and msgid2) are queried.

       nntpName xpat field range ?pattern_list?
              Returns the specified header field value for a specified message
              or for a list of messages from the current group where the  mes-
              sages  match the pattern(s) given in the pattern_list.  field is
              the title of a field in the header such as from, subject,  date,
              etc.   The information is returned in a tcl list where each ele-
              ment is of the form:

                  msgid value

              Where msgid is the number of the message and value is the  value
              set  for the queried field.  The range argument can be in any of
              the following forms:

              msgid  The message specified by msgid is queried.

              msgid1-msgid2
                     All messages between msgid1 and msgid2 (including  msgid1
                     and msgid2) are queried.

              msgid1 msgid2
                     All  messages between msgid1 and msgid2 (including msgid1
                     and msgid2) are queried.



nntp                          1.5.1                             6





nntp(n)              Tcl NNTP Client Library              nntp(n)


EXAMPLE
       A bigger example for posting a single article.


           package require nntp
           set n [nntp::nntp NNTP_SERVER]
           $n post "From: USER@DOMAIN.EXT (USER_FULL)
           Path: COMPUTERNAME!USERNAME
           Newsgroups: alt.test
           Subject: Tcl test post -ignore
           Message-ID: <[pid][clock seconds]
           @COMPUTERNAME>
           Date: [clock format [clock seconds] -format "%a, %d %
           b %y %H:%M:%S GMT" -gmt true]

           Test message body"


BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will  undoubtedly  contain
       bugs  and  other  problems.  Please report such in the category nntp of
       the         Tcllib         SF         Trackers          [http://source-
       forge.net/tracker/?group_id=12883].   Please  also report any ideas for
       enhancements you may have for either package and/or documentation.

KEYWORDS
       news, nntp, nntpclient, rfc 1036, rfc 977

CATEGORY
       Networking



























nntp                          1.5.1                             7


