MAN page from Mandrake Other perl-NNTPClient-0.28-1.i386.rpm

NNTPClient

Section: User Contributed Perl Documentation (3)
Updated: perl 5.004, patch 04
Index

NAME

News::NNTPClient - Perl 5 module to talk to NNTP (RFC977) server

DESCRIPTION

This module implements a client interface to NNTP, enabling a Perl 5application to talk to NNTP servers. It uses the OOP (Object OrientedProgramming) interface introduced with Perl 5.

USAGE

To use it in your programs, you can use either:

  use News::NNTPClient;

  require News::NNTPClient;

NNTPClient exports nothing.

A new NNTPClient object must be created with the new method. Oncethis has been done, all NNTP commands are accessed through this object.

Here are a couple of short examples. The first prints all articles inthe ``test'' newsgroup:

  #!/usr/local/bin/perl -w   use News::NNTPClient;   $c = new News::NNTPClient;   ($first, $last) = ($c->group("test"));   for (; $first <= $last; $first++) {      print $c->article($first);  }   __END__

This example prints the body of all articles in the ``test'' newsgroupnewer than one hour:

  #!/usr/local/bin/perl -w   require News::NNTPClient;   $c = new News::NNTPClient;   foreach ($c->newnews("test", time - 3600)) {      print $c->body($_);  }   __END__

NNTPClient Commands

These commands are used to manipulate the NNTPClient object, andaren't directly related to commands available on any NNTP server.

new

Use this to create a new NNTP connection. It takes three arguments, ahostname, a port and a debug flag. It calls initialize. Use anempty argument to specify defaults.

If port is omitted or blank (""), looks for environment variableNNTPPORT, service "nntp", or uses 119.

If host is omitted or empty (""), looks for environment variableNNTPSERVER or uses "news".

Examples:

  $c = new News::NNTPClient;or  $c = new News::NNTPClient("newsserver.some.where");or  $c = new News::NNTPClient("experimental", 9999);or  # Specify debug but use defaults.  $c = new News::NNTPClient("", "", 2);

Returns a blessed reference, representing a new NNTP connection.

initialize

Calls port, host, connect, and response, in that order.If any of these fail, initialization is aborted.

connect

Connects to current host/port.Not normally needed, as the new method does this for you.Closes any existing connection.Sets the posting status. See the postok method.

host

Sets the host that will be used on the next connect.Not normally needed, as the new method does this for you.

Without an argument, returns current host.

Argument can be hostname or dotted quad, for example, ``15.2.174.218''.

Returns fully qualified host name.

port

Sets the port that will be used on the next connect.Not normally needed, as the new method does this for you.

Without an argument, returns current port.

Argument can be port number or name. If it is a name, it must be avalid service.

Returns port number.

debug

Sets the debug level.

Without an argument, returns current debug level.

There are currently three debug levels. Level 0, level 1, and level2.

At level 0 the messages described for level 1 are not produced. Debuglevel 0 is a way of turning off messages produced by the default debuglevel 1. Serious error messages, such as EOF (End Of File) on thefile handle, are still produced.

At level 1, any NNTP command that results in a result code of 400 orgreater prints a warning message. This is the default.

At level 2, in addition to level 1 messages, status messages areprinted to indicate actions taking place.

Returns old debug value.

ok

Returns boolean status of most recent command. NNTP return codes lessthan 400 are considered OK. Not often needed as most commands returnfalse upon failure anyway.

okprint

Returns boolean status of most recent command. NNTP return codes lessthan 400 are considered OK. Prints an error message for return codesof 400 or greater unless debug level is set to zero (0).

This method is used internally by most commands, and could beconsidered to be ``for internal use only''. You should use the returnstatus of commands directly to determine pass-fail, or if needed theok method can be used to check status later.

message

Returns the NNTP response message of the most recent command.

Example, as returned by NNTP server version 1.5.11t:

  $c->slave;  print $c->message;

  Kinky, kinky.  I don't support such perversions.

code

Returns the NNTP response code of the most recent command.

Example:

  $c->article(1);  print $c->code, "\n";

postok

Returns the post-ability status that was reported upon connection orafter the mode_reader command.

eol

Sets the End-Of-Line termination for text returned from the server.

Returns the old EOL setting.

Default is \n.

To set EOL to nothing, pass it the empty string.

To query current EOL without setting it, call with no arguments.

Returns the old EOL termination.

Example:

  $old_eol = $c->eol();     # Get original.  $c->eol("");              # Set EOL to nothing.  @article = $c->article(); # Fetch an article.  $c->eol($old_eol);        # Restore value.

gmt

Sets GMT mode. Returns old value. To query GMT mode without settingit, call with no arguments.

A true value means that GMT mode is used in the newgroups andnewnews functions. A false value means that local time is used.

version

Returns version number.

This document represents @(#) $Revision: 0.28 $.

NNTP Commands

These commands directly correlate to NNTP server commands. Theyreturn a false value upon failure, true upon success. The truth valueis usually some bit of useful information. For example, the statcommand returns Message-ID if it is successful.

Some commands return multiple lines. These lines are returned as anarray in array context, and as a reference to an array in scalarcontext. For example, if you do this:

  @lines = $c->article(14);

then @lines will contain the article, one line per array element.However, if you do this:

  $lines = $c->article(14);

then $lines will contain a reference to an array. This feature isfor those that don't like passing arrays from routine to routine.

mode_reader

Some servers require this command to process NNTP client commands.Sets postok status. See postok.

Returns OK status.

article

Retrieves an article from the server. This is the main command forfetching articles. Expects a single argument, an article number orMessage-ID. If you use an article number, you must be in a newsgroup. See group.

Returns the header, a separating blank line, and the body of thearticle as an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of thearray itself.

Examples:

  print $c->article('<art1234AATTsoom.oom>');

  $c->group("test");

  print $c->article(99);

body

Expects a single argument, an article number or Message-ID.

Returns the body of an article as an array of lines terminated by thecurrent EOL.

In scalar context a reference to the array is returned instead of thearray itself.

See article.

head

Expects a single argument, an article number or Message-ID.

Returns the head of the article as an array of lines terminated by thecurrent EOL.

In scalar context a reference to the array is returned instead of thearray itself.

See article.

stat

Expects a single argument, an article number or Message-ID.

The STAT command is like the ARTICLE command except that it does notreturn any text. It can be used to set the ``current article pointer''if passed an article number, or to validate a Message-ID if passed aMessage-ID.

Returns Message-ID if successful, otherwise returns false.

last

The ``current article pointer'' maintained by the server is moved to theprevious article in the current news group.

Returns Message-ID if successful, otherwise returns false.

next

The ``current article pointer'' maintained by the server is moved to thenext article in the current news group.

Returns Message-ID if successful, otherwise returns false.

group

Expects a single argument, the name of a valid news group.

This command sets the current news group as maintained by the server.It also sets the server maintained ``current article pointer'' to thefirst article in the group. This enables the use of certain otherserver commands, such as article, head, body, stat,last, and next. Also sets the current group in the NNTPClientobject, which is used by the newnews and xindex commands.

Returns (first, last) in list context, or ``first-last'' in scalarcontext, where first and last are the first and last article numbersas reported by the group command. Returns false if there is an error.

It is an error to attempt to select a non-existent news group.

If the estimated article count is needed, it can be extracted from themessage. See message.

list

Accepts one optional argument that can be used indicate the type oflist desired. List type depends on server.

With an argument of ``active'' or with no arguments, this commandreturns a list of valid newsgroups and associated information. Theformat is:

  group last first p

where group is the news group name, last is the article number of thelast article, first is the article number of the first article, and pis flag indicating if posting is allowed. A `y' flag is an indicationthat posting is allowed.

Other possible arguments are: newsgroups, distributions, subscriptionsfor B-News, and active.times, distributions, distrib.pats, newsgroups,overview.fmt for INN.

Returns an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of thearray itself.

newgroups

Expects at least one argument representing the date/time in seconds,or in ``YYMMDD HHMMSS [GMT]'' format. The GMT part is optional. Ifyou wish to use GMT with the seconds format, first call gmt.Remaining arguments are used as distributions.

Example, print all new groups in the ``comp'' and/or ``news'' hierarchy asof one hour ago:

  print $c->newgroups(time() - 3600, "comp", "news");

Returns list of new news group names as an array of lines terminatedby the current EOL.

In scalar context a reference to the array is returned instead of thearray itself.

newnews

Expects one, two, or more arguments.

If the first argument is a group name, it looks for new news in thatgroup, and the date/time is the second argument. If the firstargument represents the date/time in seconds or in ``YYMMDD HHMMSS[GMT]'' format, then the group is is last group set via the groupcommand. If no group command has been issued then the group is ``*'',representing all groups. If you wish to use GMT in seconds format forthe time, first call gmt. Remaining arguments are use to restrictsearch to certain distribution(s).

Returns a list of Message-IDs of articles that have been posted orreceived since the specified time.

Examples:

  # Hour old news in news group "test".  $c->newnews("test", time() - 3600);or  # Hour old in all groups.  $c->newnews(time() - 3600);or  $c->newnews("*", time() - 3600);or  # Hour old news in news group "test".  $c->group("test");  $c->newnews(time() - 3600);

The group argument can include an asterisk ``*'' to specify a range newsgroups. It can also include multiple news groups, separated by acomma ``,''.

Example:

  $c->newnews("comp.*.sources,alt.sources", time() - 3600);

An exclamation point ``!'' may be used to negate the selection ofcertain groups.

Example:

  $c->newnews("*sources*,!*.d,!*.wanted", time() - 3600);

Any additional distribution arguments will be concatenated togetherand send as a distribution list. The distribution list will limitarticles to those that have a Distribution: header containing one ofthe distributions passed.

Example:

  $c->newnews("*", time() - 3600, "local", "na");

Returns Message-IDs of new articles as an array of lines terminated bythe current EOL.

In scalar context a reference to the array is returned instead of thearray itself.

help

Returns any server help information. The format of the information ishighly dependent on the server, but usually contains a list of NNTPcommands recognized by the server.

Returns an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of thearray itself.

post

Post an article. Expects data to be posted as an array of lines. Mostservers expect, at a minimum, Newsgroups and Subject headers. Be sureto separate the header from the body with a neck, er blank line.

Example:

  @header = ("Newsgroups: test", "Subject: test");  @body   = ("This is the body of the article");

  $c->post(@header, "", @body);

Any ``\n'' characters at the end of a line will be trimmed.

ihave

Transfer an article. Expects an article Message-ID and the article tobe sent as an array of lines.

Example:

  # Fetch article from server on $c  @article = $c->article($artid);    # Send to server on $d  if ($d->ihave($artid, @article)) {      print "Article transfered\n";  } else {      print "Article rejected: ", $d->message, "\n";  }

slave

Doesn't do anything on most servers. Included for completeness.

DESTROY

This method is called whenever the the object created byNews::NNTPClient::new is destroyed. It calls quit to close theconnection.

quit

Send the NNTP quit command and close the connection. The connectioncan be then be re-opened with the connect method. Quit willautomatically be called when the object is destroyed, so there is noneed to explicitly call quit before exiting your program.

Extended NNTP Commands

These commands also directly correlate NNTP server commands, but arenot mentioned in RFC977, and are not part of the standard. However,many servers implement them, so they are included as part of thispackage for your convenience. If a command is not recognized by aserver, the server usually returns code 500, command unrecognized.

authinfo

Expects two arguments, user and password.

date

Returns server date in ``YYYYMMDDhhmmss'' format.

listgroup

Expects one argument, a group name. Default is current group.

Returns article numbers as an array of lines terminated by the currentEOL.

In scalar context a reference to the array is returned instead of thearray itself.

xmotd

Expects one argument of unix time in seconds or as a string in theform ``YYMMDD HHMMSS''.

Returns the news servers ``Message Of The Day'' as an array of linesterminated by the current EOL.

In scalar context a reference to the array is returned instead of thearray itself.

For example, the following will always print the message of the day,if there is any:

  print $c->xmotd(1);  NNTP Server News2

  News administrator is Joseph Blough <joebloAATTnews.foo.com>

xgtitle

Expects one argument of a group pattern. Default is current group.

Returns group titles an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of thearray itself.

Example:

  print $c->xgtitle("bit.listserv.v*");

  bit.listserv.valert-l   Virus Alert List. (Moderated)  bit.listserv.vfort-l    VS-Fortran Discussion List.  bit.listserv.vm-util    VM Utilities Discussion List.  bit.listserv.vmesa-l    VM/ESA Mailing List.  bit.listserv.vmslsv-l   VAX/VMS LISTSERV Discussion List.  bit.listserv.vmxa-l     VM/XA Discussion List.  bit.listserv.vnews-l    VNEWS Discussion List.  bit.listserv.vpiej-l    Electronic Publishing Discussion

xpath

Expects one argument of an article Message-ID. Returns the path nameof the file on the server.

Example:

  print print $c->xpath(q(<43bq5l$7b5AATTnews.dtc.hp.com>))'  hp/test/4469

xhdr

Fetch header for a range of articles. First argument is name ofheader to fetch. If omitted or blank, default to Message-ID. Secondargument is start of article range. If omitted, defaults to 1. Nextargument is end of range.

Returns headers as an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of thearray itself.

Examples:

  # Fetch Message-ID of article 1.  $c->xhdr();

  # Fetch Subject of article 1.  $c->xhdr("Subject");

  # Fetch Subject of article 3345.  $c->xhdr("Subject", 3345);

  # Fetch Subjects of articles 3345-9873  $c->xhdr("Subject", 3345, 9873);

  # Fetch Message-ID of articles 3345-9873  $c->xhdr("", 3345,9873);

xpat

Fetch header for a range of articles matching one or more patterns.First argument is name of header to fetch. If omitted or blank,default to Subject. Second argument is start of article range. Ifomitted, defaults to 1. Next argument is end of range. Remainingarguments are patterns to match. Some servers use ``*'' for wildcard.

Returns headers as an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of thearray itself.

Examples:

  # Fetch Subject header of article 1.  $c->xpat();

  # Fetch "From" header of article 1.  $c->xpat("From");

  # Fetch "From" of article 3345.  $c->xpat("From", 3345);

  # Fetch "From" of articles 3345-9873 matching *foo*  $c->xpat("From", 3345, 9873, "*foo*");

  # Fetch "Subject" of articles 3345-9873 matching  # *foo*, *bar*, *and*, *stuff*  $c->xpat("", 3345,9873, qw(*foo* *bar* *and* *stuff*));

xover

Expects an article number or a starting and ending article numberrepresenting a range of articles.

Returns overview information for each article as an array of linesterminated by the current EOL.

In scalar context a reference to the array is returned instead of thearray itself.

Xover generally returns items separated by tabs. Here is an examplethat prints out the xover fields from all messages in the ``test'' newsgroup.

  #!/usr/local/bin/perl

  require News::NNTPClient;

  $c = new News::NNTPClient;

  @fields = qw(numb subj from date mesg refr char line xref);

  foreach $xover ($c->xover($c->group("test"))) {      %fields = ();      @fields{@fields} = split /\t/, $xover;      print map { "$_: $fields{$_}\n" } @fields;      print "\n";  }

  __END__

xthread

Expects zero or one argument. Value of argument doesn't matter. Ifpresent, dbinit command is sent. If absent, thread command issent.

Returns binary data as a scalar value.

Format of data returned is unknown at this time.

xindex

Expects one argument, a group name. If omitted, defaults to the groupset by last group command. If there hasn't been a group command,it returns an error;

Returns index information for group as an array of lines terminated bythe current EOL.

In scalar context a reference to the array is returned instead of thearray itself.

xsearch

Expects a query as an array of lines which are sent to the server,much like post. Returns the result of the search as an array of linesor a reference to same.

Format of query is unknown at this time.

AUTHOR

Rodger Anderson <rodgerAATTboi.hp.com>

COPYRIGHT

This document was created byman2html,using the manual pages.