Net::NNTP Client Library

→ ‘nntp’

What

This gem allows you to to retrieve and post Usenet news articles via NNTP, the Network News Transfer Protocol. For details of NNTP itself, see RFC977.

This library does NOT provide functions to compose Usenet news articles. You must create and format them yourself per Standard for Interchange of Usenet Messages. See RFC850, RFC2047.

Installing

sudo gem install nntp

Alternatively, you may download the gem from the project info page and install manually.

The basics

Posting Messages

You must open a connection to a NNTP server before posting messages. The first argument is the address of your NNTP server, and the second argument is the port number. Using NNTP.start with a block is the simplest way to do this because the NNTP connection closes automatically after the block executes.

  require 'rubygems'
  require 'nntp'
  Net::NNTP.start('your.nntp.server', 119) do |nntp|
    # Use the NNTP object nntp only in this block.
  end

Replace ‘your.nntp.server’ with your NNTP server. Normally your systems administrator or internet service provider supplies a server for you.

Then you can post messages.

  require 'date'
  date = DateTime.now().strftime(fmt='%a, %d %b %Y %T %z')

  msgstr = <<END_OF_MESSAGE
  From: Your Name <your@mail.address>
  Newsgroups: news.group.one, news.group.two ...
  Subject: test message
  Date: #{date}

  This is a test message.
  END_OF_MESSAGE

  require 'rubygems'
  require 'nntp'
  Net::NNTP.start('your.nntp.server', 119) do |nntp|
    nntp.post msgstr
  end

NOTE: The NNTP message headers such as Date:, Message-ID:, and Path:, if ommited, may automatically be added by your Usenet news server; however, it is best not to rely on this behavior.

Reading Messages

This snippet will display all subject lines within a particular news group.

  require 'rubygems'
  require 'nntp'

  newsgroup = 'comp.lang.ruby'

  Net::NNTP.start('your.nntp.server', 119) do |nntp|
    message_ids = nntp.listgroup(newsgroup)
    nntp.group(newsgroup)
    message_ids[1].each do |id|
      nntp.head(id).each do |header|
        header.each { |line| puts(line) if line.index('Subject:') }
        end
    end
  end

Closing the Session

You MUST close the NNTP session after posting messages by calling the Net::NNTP#finish method:

  # using NNTP#finish
  nntp = Net::NNTP.start('your.nntp.server', 119)
  nntp.post msgstr
  nntp.finish

You can also use the block form of NNTP.start/NNTP#start. This closes the NNTP session automatically:

  # using block form of NNTP.start
  Net::NNTP.start('your.nntp.server', 119) do |nntp|
    nntp.post msgstr
  end

We strongly recommend the latter scheme since it is simpler and more robust.

NNTP Authentication

The Net::NNTP class may support various authentication schemes depending on your news server‘s reponse to CAPABILITIES command. To use NNTP authentication, pass extra arguments to NNTP.start/NNTP#start.

See NNTP Extension for Authentication.

  Net::NNTP.start('your.nntp.server', 119,
                  'YourAccountName', 'YourPassword', :method)

Where :method can be one of ‘gassapi’, ‘digest_md5’, ‘cram_md5’, ‘starttls’, ‘external’, ‘plain’, ‘generic’, ‘simple’ or ‘original’.

In the case of method :generic, arguments should be passed to a format string as follows:

  Net::NNTP.start('your.nntp.server', 119,
                  "format", *arguments, :generic)

NOTE: With the exception of :generic, the authentication mechanism will fallback to a less secure scheme if your Usenet server does not support the method you selected.

How to Submit Patches

• Read the 8 steps for fixing other people’s code.
• The trunk repository is svn://rubyforge.org/var/svn/nntp/trunk for anonymous access.
• You can upload your patch to the “Patches” section of the project info page.

License

This code is free to use under the terms of version 2.1 of the GNU Lesser General Public License.

Donate

Any contribution of yours, however small it may be, will highly be appreciated and used for further development of this and other F/LOSS (Free/Libre Open Source Software) Projects.

Documentation

In addition to this page, you can also view the automatically generated RDocs in the “DocManager: Project Documentation” section of the project info page. If you elect to install the RI documentation when you install the gem, you can afterwards issue the following command for the API reference:

ri Net::NNTP

Similar Gems

Anton Bangratz’s ruby-net-nntp

Credits

• RubyForge – hosting and project management
• newgem – new gem generator

Where to get help

If you need assistance with this gem, visit the project info page to file a bug, make a support request, or suggest a new feature.

Albert Vernon, 2nd January 2008
Theme extended from Paul Battley