nntp-matthis

Description

node-nntp is an NNTP (usenet/newsgroups) client module for node.js.

Requirements

• node.js -- v0.8.0 or newer

Examples

• Get the headers and body of the first message in 'misc.test'

    var NNTP = require('nntp'),
        inspect = require('util').inspect;

    var c = new NNTP();
    c.on('ready', function() {
      c.group('misc.test', function(err, count, low, high) {
        if (err) throw err;
      });
      c.article(function(err, n, id, headers, body) {
        if (err) throw err;
        console.log('Article #' + n);
        console.log('Article ID: ' + id);
        console.log('Article headers: ' + inspect(headers));
        console.log('Article body: ' + inspect(body.toString()));
      });
    });
    c.on('error', function(err) {
      console.log('Error: ' + err);
    });
    c.on('close', function(had_err) {
      console.log('Connection closed');
    });
    c.connect({
      host: 'example.org',
      user: 'foo',
      password: 'bar'
    });

• Get a list of all newsgroups beginning with 'alt.binaries.'

    var NNTP = require('nntp'),
        inspect = require('util').inspect;

    var c = new NNTP();
    c.on('ready', function() {
      c.groups('alt.binaries.*', function(err, list) {
        if (err) throw err;
        console.dir(list);
      });
    });
    c.on('error', function(err) {
      console.log('Error: ' + err);
    });
    c.on('close', function(had_err) {
      console.log('Connection closed');
    });
    c.connect({
      host: 'example.org',
      user: 'foo',
      password: 'bar'
    });

• Post a message to alt.test:

    var NNTP = require('nntp'),
        inspect = require('util').inspect;

    var c = new NNTP();
    c.on('ready', function() {
      var msg = {
        from: { name: 'Node User', email: '[e-mail]' },
        groups: 'alt.test',
        subject: 'Just testing, do not mind me',
        body: 'node.js rules!'
      };
      c.post(msg, function(err) {
        if (err) throw err;
      });
    });
    c.on('error', function(err) {
      console.log('Error: ' + err);
    });
    c.on('close', function(had_err) {
      console.log('Connection closed');
    });
    c.connect({
      host: 'example.org',
      user: 'foo',
      password: 'bar'
    });

API

Events

• ready() - Emitted when connection and authentication were successful.

• close(< boolean >hadErr) - Emitted when the connection has fully closed.

• end() - Emitted when the connection has ended.

• error(< Error >err) - Emitted when an error occurs. In case of protocol-level errors, err contains a 'code' property that references the related NNTP response code.

Methods

• (constructor)() - Creates and returns a new NNTP client instance.

• connect(< object >config) - (void) - Attempts to connect to a server. Valid config properties are:

  • host - < string > - Hostname or IP address of the server. Default: 'localhost'

  • port - < integer > - Port number of the server. Default: 119

  • secure - < boolean > - Will this be a secure (TLS) connection? Default: false

  • user - < string > - Username for authentication. Default: (none)

  • password - < string > - Password for password-based user authentication. Default: (none)

  • connTimeout - < integer > - Connection timeout in milliseconds. Default: 60000

• end() - (void) - Ends the connection with the server.

Mandatory/Common protocol commands

• dateTime(< function >callback) - (void) - Retrieves the server's UTC date and time in YYYYMMDDHHMMSS format. callback has 2 parameters: < Error >err, < string >datetime.

• stat([< string >which, ]< function >callback) - (void) - Retrieves the article number and message ID for the current article if which is not given or for the article whose number or message ID is what. callback has 3 parameters: < Error >err, < integer >articleNum, < string >msgID.

• group(< string >group, < function >callback) - (void) - Sets the current newsgroup to group. callback has 4 parameters: < Error >err, < integer >estimatedArticleCount, < integer >firstArticleNum, < integer >lastArticleNum.

• next(< function >callback) - (void) - Attempts to move to the next article in the current newsgroup. callback has 3 parameters: < Error >err, < integer >articleNum, < string >msgID.

• prev(< function >callback) - (void) - Attempts to move to the previous article in the current newsgroup. callback has 3 parameters: < Error >err, < integer >articleNum, < string >msgID.

• headers([< string >which, ]< function >callback) - (void) - Retrieves the headers of the current article if which is not given or for the article whose number or message ID is what. callback has 4 parameters: < Error >err, < integer >articleNum, < string >msgID, < object >headers. headers values are always arrays (of strings).

• body([< string >which, ]< function >callback) - (void) - Retrieves the body of the current article if which is not given or for the article whose number or message ID is what. callback has 4 parameters: < Error >err, < integer >articleNum, < string >msgID, < Buffer >body.

• article([< string >which, ]< function >callback) - (void) - Retrieves the headers and body of the current article if which is not given or for the article whose number or message ID is what. callback has 5 parameters: < Error >err, < integer >articleNum, < string >msgID, < object >headers, < Buffer >body. headers values are always arrays (of strings).

Extended protocol commands -- these may not be implemented or enabled on all servers

* Note: A filter parameter is a single (or Array of) wildcard-capable newsgroup name filter string(s) (information on the wildcard format and wildcard examples).

• newNews(< mixed >filter, < mixed >date, [< string >time, ] < function >callback) - (void) - Retrieves the message ID of articles in group(s) matching filter on or after a date. This date can be specified with date being a Date object, or date being a 'YYYYMMDD'-formatted string and time being a 'HHMMSS'-formatted string (defaults to midnight) in UTC/GMT. callback has 2 parameters: < Error >err, < array >msgIDs.

• groups(< mixed >filter, < function >callback) - (void) - Retrieves a list of groups matching filter. callback has 2 parameters: < Error >err, < array >groupsInfo. groupsInfo is an array of [groupName, firstArticleNum, lastArticleNum, status] rows. Valid statuses are documented here.

• groupsDesc(< mixed >filter, < function >callback) - (void) - Retrieves a list of group descriptions matching filter. callback has 2 parameters: < Error >err, < array >groups. groups is an array of [groupName, groupDesc] rows.

• post(< object >msg, < function >callback) - (void) - Posts the given msg (as defined below) to the current newsgroup. callback has 1 parameter: < Error >err.

  • from - < object > - Who the message is from.

    • name - < string > - Example: 'User'.

    • email - < string > - Example: '[e-mail]'.

  • groups - < mixed > - A single newsgroup or array of newsgroups to post this message to.

  • subject - < string > - The subject line.

  • body - < mixed > - The body content -- a string or a Buffer (will be converted to UTF-8 string).

  • references - < string > - Optional string containing the message ids of referenced posts.

• For methods that return first and last article numbers, the RFC says a group is empty if one of the following is true:

  • The last article number will be one less than the first article number, and the estimated article count will be zero. This is the only time that the last article number can be less than the first article number.

  • First and last article numbers (and estimated article count where applicable) are all 0.

  • The last article number is equal to the first article number. The estimated article count might be zero or non-zero.