Net::NNTP

Net::NNTP is one of the libnet modules. It provides methods for developing a news client to interface with an NNTP server. Net::NNTP implements the NNTP protocol as defined in RFC 977, as well as a number of extensions defined in the IETF Internet Draft document mentioned earlier.

For example, the following code:

$nntp->post(@message);

is equivalent to issuing the post command and associated X-headers directly to an NNTP server on port 119.

Initializing the NNTP Client

To use Net::NNTP, create a new Net::NNTP object:

use Net::NNTP; $nntp = Net::NNTP->new; # Use default port and options

Once you've created the object, you can use any of the Net::NNTP methods on that object. The Net::NNTP methods generally parallel the functionality of the raw NNTP commands. Your news client can be written to perform many functions, including:

• Authenticating a user to the server
• Listing available newsgroups
• Retrieving news headers and articles
• Extracting headers
• Checking for new articles
• Posting articles
• Listing information such as active messages in a newsgroup, new newsgroups, valid distribution areas, or message IDs of newly arrived messages

Net::NNTP Reference

Net::NNTP includes methods that implement many of the extensions to RFC 977; the description indicates if a method is an extension. Extensions that are not supported by Net::NNTP are AUTHINFO, GENERIC, XINDEX, XSEARCH, and XTHREAD. In addition, some extensions supported by Net::NNTP may not be supported by a particular server.

Unless otherwise stated, all the methods return either true or false to indicate success or failure. If a method returns a value instead, then it returns undef or an empty list to indicate failure.

In this list, message-spec refers to a single message ID, a single message number, or a reference to a list of two message numbers. It can also be passed as a list of two message numbers, but this is for compatibility only and is now deprecated.

Where pattern-matching is indicated, the matching is done according to the NNTP specification. See the Net::NNTP documentation for details.

$nntp = Net::NNTP->new([host[, options]]) 

Constructor. Creates a new Net::NNTP object. Arguments are:

• host
• The name of the remote host to which an NNTP connection is required. If not specified, the constructor checks the environment variables NNTPSERVER and NEWSHOST, in that order, then Net::Config. Defaults to news if nothing is found.
• options
• Options. Passed as key/value pairs. Possible options are:
  • Timeout
  • Maximum time, in seconds, to wait for a response from the NNTP server. Default is 120 seconds. A value of causes all I/O operations to block.
  • Debug
  • Enables printing of debugging information to STDERR.

$nntp->active([pattern]) 

Similar to list, but returns only active groups that match the pattern (an extension).

$nntp->active_times( ) 

Returns a reference to a hash in which the keys are the group names, and the values are references to arrays containing the time the group was created and an identifier, possibly an email address, for the creator (an extension).

$nntp->article([msgid|msgnum]) 

Retrieves the header, a blank line, then the body (text) of the article, specified as either a message ID or a message number. With no arguments, returns the current article in the current newsgroup as a reference to an array containing the article.

$nntp->authinfo(user, pass) 

Authenticates the user to the server, passing the user's username and password.

$nntp->body([msgid|msgnum]) 

Retrieves the body (text) of the article specified by either a message ID or a message number. Takes the same arguments as article. Returns a reference to an array containing the body of the article.

$nntp->date( ) 

Returns the date on the remote server, in Unix time format (seconds since 1970).

$nntp->distributions( ) 

Returns a reference to a hash in which the keys are the valid distribution names, and the values are the distribution descriptions (an extension).

$nntp->group([group]) 

Sets and/or gets the current group. With no argument, returns information about the current group; otherwise, sets the current group to group.

In a scalar context, group returns the group name. In an array context, it returns a list containing the number of articles in the group, the first article number, the last article number, and the group name.

$nntp->head([msgid|msgnum]) 

Retrieves the header of the article specified by msgid or msgnum. Takes the same arguments as article and returns a reference to an array containing the article's header.

$nntp->ihave(msgid[, message]) 

Informs the server that the client has an article whose ID is msgid. The optional argument message can be either an array of lines or a reference to an array. If message is specified, and the server wants a copy, it is sent, returning true on successful completion.

If message is not specified, then the message must be sent using the Net::Cmd datasend and dataend methods.

$nntp->last( ) 

Sets the current article pointer to the previous article in the current newsgroup. Returns the article's message ID.

$nntp->list( ) 

Returns information about all active newsgroups. The result is a reference to a hash in which the key is a newsgroup name, and each value is a reference to an array. The elements in the array are the first article number in the group, the last article number in the group, and any information flags.

$nntp->listgroup([group]) 

Returns a reference to a list of all active messages in newsgroup group, or the current newsgroup if group is not specified (an extension).

$nntp->newgroups(since[, distributions]) 

Like list, but returns groups created after a certain time and optionally in one of a set of distribution areas. Arguments are:

• since
• Time value; only groups created after this time should be returned.
• distributions
• Optional distribution pattern or reference to a list of distribution patterns. If present, only groups matching a specified distribution area should be returned.

$nntp->newnews(since[, groups[, distributions]]) 

Returns a reference to a list containing the message IDs of all news posted after since that are in newsgroups matching groups, with a distribution that matches distributions. Arguments are:

• since
• Time value; only groups created after this time should be returned.
• groups
• Optional group pattern or reference to a list of group patterns indicating which groups should be checked for new messages.
• distributions
• Optional distribution pattern or reference to a list of distribution patterns. If present, only groups matching a specified distribution area should be returned.

$nntp->newsgroups([pattern]) 

Returns a reference to a hash in which the keys are all newsgroup names that match pattern, or all newsgroups if no pattern is specified, and each value contains the description text for the group (an extension).

$nntp->next( ) 

Sets the current article pointer to the next article in the current newsgroup. Returns the message ID of the article.

$nntp->nntpstat([msgid|msgnum]) 

Similar to article, except that no text is returned. When selecting by message number within a newsgroup, sets the current article pointer without sending text. Selecting by message ID is valid, but doesn't alter the current article pointer and therefore is of little use. Returns the message ID of the current article.

$nntp->overview_fmt( ) 

Returns a reference to an array containing the names of the fields returned by xover (an extension).

$nntp->post([message]) 

Posts a new article to the news server. If message is specified and posting is allowed, then the message is sent. If message is not specified, the message must be sent using the Net::Cmd datasend and dataend methods. message can be either an array of lines or a reference to an array.

$nntp->postok( ) 

Returns true if the server's initial response indicated that it allows posting.

$nntp->quit( ) 

Quits the remote server and closes the socket connection.

$nntp->reader( ) 

Tells the server that you are a reader and not another server; required by some servers (an extension).

$nntp->slave( ) 

Tells the remote server that this is not a user client, but is probably another news server.

$nntp->subscriptions( ) 

Returns a reference to a default list of newsgroups recommended for new users to subscribe to (an extension).

$nntp->xgtitle(pattern) 

Returns a reference to a hash in which the keys are all the newsgroup names that match pattern, and each value is the text of the newsgroup's description (an extension).

$nntp->xhdr(header, message-spec) 

Gets the header field header for all the messages specified in message-spec. Returns a reference to a hash in which the keys are the message numbers, and each value contains the text of the requested header for that message (an extension).

$nntp->xover(message-spec) 

Returns a reference to a hash in which the keys are the message numbers, and each value contains a reference to an array of the overview fields for that message (an extension).

The names of the fields can be obtained by calling overview_fmt.

$nntp->xpat(header, pattern, message-spec) 

Like xhdr, but returns only headers in which the text of the header matches pattern (an extension).

$nntp->xpath(message-id) 

Returns the path to the file on the server that contains the specified message (an extension).

$nntp->xrover(message-spec) 

Returns reference information for the article(s) specified. Returns a reference to a hash in which the keys are the message numbers, and the values are the References: lines from the articles (an extension).