class Net::NNTP

Overview

Net::NNTP

What is This Library?

This library provides functionality to retrieve and, or post Usenet news articles via NNTP, the Network News Transfer Protocol. The Usenet is a world-wide distributed discussion system. It consists of a set of "newsgroups" with names that are classified hierarchically by topic. "articles" or "messages" are "posted" to these newsgroups by people on computers with the appropriate software -- these articles are then broadcast to other interconnected NNTP servers via a wide variety of networks. For details of NNTP itself, see RFC977.

What is This Library NOT?

This library does NOT provide functions to compose Usenet news. You must create and, or format them yourself as per guidelines per Standard for Interchange of Usenet messages, see RFC850, RFC2047 and a fews other RFC's.

FYI: the official documentation on Usenet news extentions is: RFC2980.

Included Modules

Defined in:

net/nntp.cr:3
net/nntp.cr:31
nntp-lib/version.cr

Constant Summary

DEFAULT_PORT = 119

The default NNTP port, port 119.

Log = ::Log.for(self)
VERSION = "1.2.2"

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from module Net::NNTP::Commands::Auth

authenticate(user, secret, method = :original) authenticate

Instance methods inherited from module Net::NNTP::Commands::Extensions

date : Net::NNTP::Response date, list_active(wildmat = "") list_active, list_active_times list_active_times, list_distrib_pats list_distrib_pats, list_distributions list_distributions, list_newsgroups(wildmat = "") list_newsgroups, list_overview_fmt list_overview_fmt, list_subscriptions list_subscriptions, listgroup(group = "") listgroup, mode_reader : Net::NNTP::Response mode_reader, mode_stream : Net::NNTP::Response mode_stream, xdhr(header, num : Int64 | Int32, end_num : Int64 | Int32 | Nil = nil, all : Bool = false) xdhr, xover(num : Int64 | Int32, end_num : Int64 | Int32 | Nil = nil, all : Bool = false) xover

Instance methods inherited from module Net::NNTP::Commands

article(message_id : String)
article(num : Int64 | Int32 = 0) article, body(message_id : String)
body(num : Int64 | Int32 = 0) body, group(name) group, head(message_id : String)
head(num : Int64 | Int32 = 0) head, help : Net::NNTP::Response help, last last, list(args : String)
list list, new_groups(date, time, tzone : String = "UTC", distributions : Array(String) | Nil = nil)
new_groups new_groups, new_news(newsgroups, date, time, tzone : String = "UTC", distributions : Array(String) | Nil = nil)
new_news(newsgroups : String = "*") new_news, next next, quit : Net::NNTP::Response quit, slave : Net::NNTP::Response slave, stat(message_id : String)
stat(num : Int64 | Int32 = 0) stat

Constructor Detail

def self.new(address : String, port : Int32 | Nil = nil, use_ssl : Bool = true, open_timeout : Int32 = 30, read_timeout : Int32 = 60, **args) #

Creates a new Net::NNTP object.

address is the hostname or ip address of your NNTP server. port is the port to connect to; it defaults to port 119.

This method does not opens any TCP connection. You can use Net::NNTP.start instead of .new if you want to do everything at once. Otherwise, follow .new with #start.


[View source]

Class Method Detail

def self.default_port #

The default NNTP port, port 119.


[View source]
def self.start(address, port : Int32 | Nil = nil, use_ssl = true, open_timeout : Int32 = 30, read_timeout : Int32 = 60, user : String | Nil = nil, secret : String | Nil = nil, method = :original) #

[View source]

Instance Method Detail

def address : String #

The address of the NNTP server to connect to.


[View source]
def finish #

Will send the quit command and close the socket.


[View source]
def port : Int32 #

The port number of the NNTP server to connect to.


[View source]
def start(user, secret, method) #

Opens a TCP connection and starts the NNTP session.

Parameters

If both of user and secret are given, NNTP authentication will be attempted using the AUTH command. The method specifies the type of authentication to attempt; it must be one of Net::NNTP::Commands::Auth::AUTH_METHODS. See the discussion of NNTP Authentication in the overview notes.

Block Usage

When this methods is called with a block, the newly-started NNTP object is yielded to the block, and automatically closed after the block call finishes. Otherwise, it is the caller's responsibility to close the session when finished via #finish.

Example

This is very similar to the class method NNTP.start.

require "nntp-lib"

nntp = Net::NNTP.new("secure.usenetserver.com", 563)
nntp.start(user: "myuser", secret: "pass", :original)

# Perform nntp requests here

nntp.finish

With block that will call #finish when complete

require "nntp-lib"

nntp = Net::NNTP.new("secure.usenetserver.com", 563)
nntp.start(user: "myuser", secret: "pass", :original) do |socket|
  # Perform nntp requests here
end

The primary use of this method (as opposed to NNTP.start) is probably to delay socket creation and connection till a later time.

Errors

If session has already been started, an IO::Error will be raised.

This method may raise:


[View source]
def start(user, secret, method, &) #

Opens a TCP connection and starts the NNTP session.

Parameters

If both of user and secret are given, NNTP authentication will be attempted using the AUTH command. The method specifies the type of authentication to attempt; it must be one of Net::NNTP::Commands::Auth::AUTH_METHODS. See the discussion of NNTP Authentication in the overview notes.

Block Usage

When this methods is called with a block, the newly-started NNTP object is yielded to the block, and automatically closed after the block call finishes. Otherwise, it is the caller's responsibility to close the session when finished via #finish.

Example

This is very similar to the class method NNTP.start.

require "nntp-lib"

nntp = Net::NNTP.new("secure.usenetserver.com", 563)
nntp.start(user: "myuser", secret: "pass", :original)

# Perform nntp requests here

nntp.finish

With block that will call #finish when complete

require "nntp-lib"

nntp = Net::NNTP.new("secure.usenetserver.com", 563)
nntp.start(user: "myuser", secret: "pass", :original) do |socket|
  # Perform nntp requests here
end

The primary use of this method (as opposed to NNTP.start) is probably to delay socket creation and connection till a later time.

Errors

If session has already been started, an IO::Error will be raised.

This method may raise:


[View source]
def started? #

Will return true if #start has been called and the socket is open


[View source]