[ Index ]

PHP Cross Reference of Unnamed Project

title

Body

[close]

/se3-unattended/var/se3/unattended/install/linuxaux/opt/perl/lib/5.10.0/Net/ -> NNTP.pm (source)

   1  # Net::NNTP.pm
   2  #
   3  # Copyright (c) 1995-1997 Graham Barr <gbarr@pobox.com>. All rights reserved.
   4  # This program is free software; you can redistribute it and/or
   5  # modify it under the same terms as Perl itself.
   6  
   7  package Net::NNTP;
   8  
   9  use strict;
  10  use vars qw(@ISA $VERSION $debug);
  11  use IO::Socket;
  12  use Net::Cmd;
  13  use Carp;
  14  use Time::Local;
  15  use Net::Config;
  16  
  17  $VERSION = "2.24";
  18  @ISA     = qw(Net::Cmd IO::Socket::INET);
  19  
  20  
  21  sub new {
  22    my $self = shift;
  23    my $type = ref($self) || $self;
  24    my ($host, %arg);
  25    if (@_ % 2) {
  26      $host = shift;
  27      %arg  = @_;
  28    }
  29    else {
  30      %arg  = @_;
  31      $host = delete $arg{Host};
  32    }
  33    my $obj;
  34  
  35    $host ||= $ENV{NNTPSERVER} || $ENV{NEWSHOST};
  36  
  37    my $hosts = defined $host ? [$host] : $NetConfig{nntp_hosts};
  38  
  39    @{$hosts} = qw(news)
  40      unless @{$hosts};
  41  
  42    my $h;
  43    foreach $h (@{$hosts}) {
  44      $obj = $type->SUPER::new(
  45        PeerAddr => ($host = $h),
  46        PeerPort => $arg{Port} || 'nntp(119)',
  47        Proto => 'tcp',
  48        Timeout => defined $arg{Timeout}
  49        ? $arg{Timeout}
  50        : 120
  51        )
  52        and last;
  53    }
  54  
  55    return undef
  56      unless defined $obj;
  57  
  58    ${*$obj}{'net_nntp_host'} = $host;
  59  
  60    $obj->autoflush(1);
  61    $obj->debug(exists $arg{Debug} ? $arg{Debug} : undef);
  62  
  63    unless ($obj->response() == CMD_OK) {
  64      $obj->close;
  65      return undef;
  66    }
  67  
  68    my $c = $obj->code;
  69    my @m = $obj->message;
  70  
  71    unless (exists $arg{Reader} && $arg{Reader} == 0) {
  72  
  73      # if server is INN and we have transfer rights the we are currently
  74      # talking to innd not nnrpd
  75      if ($obj->reader) {
  76  
  77        # If reader suceeds the we need to consider this code to determine postok
  78        $c = $obj->code;
  79      }
  80      else {
  81  
  82        # I want to ignore this failure, so restore the previous status.
  83        $obj->set_status($c, \@m);
  84      }
  85    }
  86  
  87    ${*$obj}{'net_nntp_post'} = $c == 200 ? 1 : 0;
  88  
  89    $obj;
  90  }
  91  
  92  
  93  sub host {
  94    my $me = shift;
  95    ${*$me}{'net_nntp_host'};
  96  }
  97  
  98  
  99  sub debug_text {
 100    my $nntp  = shift;
 101    my $inout = shift;
 102    my $text  = shift;
 103  
 104    if ( (ref($nntp) and $nntp->code == 350 and $text =~ /^(\S+)/)
 105      || ($text =~ /^(authinfo\s+pass)/io))
 106    {
 107      $text = "$1 ....\n";
 108    }
 109  
 110    $text;
 111  }
 112  
 113  
 114  sub postok {
 115    @_ == 1 or croak 'usage: $nntp->postok()';
 116    my $nntp = shift;
 117    ${*$nntp}{'net_nntp_post'} || 0;
 118  }
 119  
 120  
 121  sub article {
 122    @_ >= 1 && @_ <= 3 or croak 'usage: $nntp->article( [ MSGID ], [ FH ] )';
 123    my $nntp = shift;
 124    my @fh;
 125  
 126    @fh = (pop) if @_ == 2 || (@_ && (ref($_[0]) || ref(\$_[0]) eq 'GLOB'));
 127  
 128    $nntp->_ARTICLE(@_)
 129      ? $nntp->read_until_dot(@fh)
 130      : undef;
 131  }
 132  
 133  
 134  sub articlefh {
 135    @_ >= 1 && @_ <= 2 or croak 'usage: $nntp->articlefh( [ MSGID ] )';
 136    my $nntp = shift;
 137  
 138    return unless $nntp->_ARTICLE(@_);
 139    return $nntp->tied_fh;
 140  }
 141  
 142  
 143  sub authinfo {
 144    @_ == 3 or croak 'usage: $nntp->authinfo( USER, PASS )';
 145    my ($nntp, $user, $pass) = @_;
 146  
 147    $nntp->_AUTHINFO("USER",      $user) == CMD_MORE
 148      && $nntp->_AUTHINFO("PASS", $pass) == CMD_OK;
 149  }
 150  
 151  
 152  sub authinfo_simple {
 153    @_ == 3 or croak 'usage: $nntp->authinfo( USER, PASS )';
 154    my ($nntp, $user, $pass) = @_;
 155  
 156    $nntp->_AUTHINFO('SIMPLE') == CMD_MORE
 157      && $nntp->command($user, $pass)->response == CMD_OK;
 158  }
 159  
 160  
 161  sub body {
 162    @_ >= 1 && @_ <= 3 or croak 'usage: $nntp->body( [ MSGID ], [ FH ] )';
 163    my $nntp = shift;
 164    my @fh;
 165  
 166    @fh = (pop) if @_ == 2 || (@_ && ref($_[0]) || ref(\$_[0]) eq 'GLOB');
 167  
 168    $nntp->_BODY(@_)
 169      ? $nntp->read_until_dot(@fh)
 170      : undef;
 171  }
 172  
 173  
 174  sub bodyfh {
 175    @_ >= 1 && @_ <= 2 or croak 'usage: $nntp->bodyfh( [ MSGID ] )';
 176    my $nntp = shift;
 177    return unless $nntp->_BODY(@_);
 178    return $nntp->tied_fh;
 179  }
 180  
 181  
 182  sub head {
 183    @_ >= 1 && @_ <= 3 or croak 'usage: $nntp->head( [ MSGID ], [ FH ] )';
 184    my $nntp = shift;
 185    my @fh;
 186  
 187    @fh = (pop) if @_ == 2 || (@_ && ref($_[0]) || ref(\$_[0]) eq 'GLOB');
 188  
 189    $nntp->_HEAD(@_)
 190      ? $nntp->read_until_dot(@fh)
 191      : undef;
 192  }
 193  
 194  
 195  sub headfh {
 196    @_ >= 1 && @_ <= 2 or croak 'usage: $nntp->headfh( [ MSGID ] )';
 197    my $nntp = shift;
 198    return unless $nntp->_HEAD(@_);
 199    return $nntp->tied_fh;
 200  }
 201  
 202  
 203  sub nntpstat {
 204    @_ == 1 || @_ == 2 or croak 'usage: $nntp->nntpstat( [ MSGID ] )';
 205    my $nntp = shift;
 206  
 207    $nntp->_STAT(@_) && $nntp->message =~ /(<[^>]+>)/o
 208      ? $1
 209      : undef;
 210  }
 211  
 212  
 213  sub group {
 214    @_ == 1 || @_ == 2 or croak 'usage: $nntp->group( [ GROUP ] )';
 215    my $nntp = shift;
 216    my $grp  = ${*$nntp}{'net_nntp_group'} || undef;
 217  
 218    return $grp
 219      unless (@_ || wantarray);
 220  
 221    my $newgrp = shift;
 222  
 223    return wantarray ? () : undef
 224      unless $nntp->_GROUP($newgrp || $grp || "")
 225      && $nntp->message =~ /(\d+)\s+(\d+)\s+(\d+)\s+(\S+)/;
 226  
 227    my ($count, $first, $last, $group) = ($1, $2, $3, $4);
 228  
 229    # group may be replied as '(current group)'
 230    $group = ${*$nntp}{'net_nntp_group'}
 231      if $group =~ /\(/;
 232  
 233    ${*$nntp}{'net_nntp_group'} = $group;
 234  
 235    wantarray
 236      ? ($count, $first, $last, $group)
 237      : $group;
 238  }
 239  
 240  
 241  sub help {
 242    @_ == 1 or croak 'usage: $nntp->help()';
 243    my $nntp = shift;
 244  
 245    $nntp->_HELP
 246      ? $nntp->read_until_dot
 247      : undef;
 248  }
 249  
 250  
 251  sub ihave {
 252    @_ >= 2 or croak 'usage: $nntp->ihave( MESSAGE-ID [, MESSAGE ])';
 253    my $nntp = shift;
 254    my $mid  = shift;
 255  
 256    $nntp->_IHAVE($mid) && $nntp->datasend(@_)
 257      ? @_ == 0 || $nntp->dataend
 258      : undef;
 259  }
 260  
 261  
 262  sub last {
 263    @_ == 1 or croak 'usage: $nntp->last()';
 264    my $nntp = shift;
 265  
 266    $nntp->_LAST && $nntp->message =~ /(<[^>]+>)/o
 267      ? $1
 268      : undef;
 269  }
 270  
 271  
 272  sub list {
 273    @_ == 1 or croak 'usage: $nntp->list()';
 274    my $nntp = shift;
 275  
 276    $nntp->_LIST
 277      ? $nntp->_grouplist
 278      : undef;
 279  }
 280  
 281  
 282  sub newgroups {
 283    @_ >= 2 or croak 'usage: $nntp->newgroups( SINCE [, DISTRIBUTIONS ])';
 284    my $nntp = shift;
 285    my $time = _timestr(shift);
 286    my $dist = shift || "";
 287  
 288    $dist = join(",", @{$dist})
 289      if ref($dist);
 290  
 291    $nntp->_NEWGROUPS($time, $dist)
 292      ? $nntp->_grouplist
 293      : undef;
 294  }
 295  
 296  
 297  sub newnews {
 298    @_ >= 2 && @_ <= 4
 299      or croak 'usage: $nntp->newnews( SINCE [, GROUPS [, DISTRIBUTIONS ]])';
 300    my $nntp = shift;
 301    my $time = _timestr(shift);
 302    my $grp  = @_ ? shift: $nntp->group;
 303    my $dist = shift || "";
 304  
 305    $grp ||= "*";
 306    $grp = join(",", @{$grp})
 307      if ref($grp);
 308  
 309    $dist = join(",", @{$dist})
 310      if ref($dist);
 311  
 312    $nntp->_NEWNEWS($grp, $time, $dist)
 313      ? $nntp->_articlelist
 314      : undef;
 315  }
 316  
 317  
 318  sub next {
 319    @_ == 1 or croak 'usage: $nntp->next()';
 320    my $nntp = shift;
 321  
 322    $nntp->_NEXT && $nntp->message =~ /(<[^>]+>)/o
 323      ? $1
 324      : undef;
 325  }
 326  
 327  
 328  sub post {
 329    @_ >= 1 or croak 'usage: $nntp->post( [ MESSAGE ] )';
 330    my $nntp = shift;
 331  
 332    $nntp->_POST() && $nntp->datasend(@_)
 333      ? @_ == 0 || $nntp->dataend
 334      : undef;
 335  }
 336  
 337  
 338  sub postfh {
 339    my $nntp = shift;
 340    return unless $nntp->_POST();
 341    return $nntp->tied_fh;
 342  }
 343  
 344  
 345  sub quit {
 346    @_ == 1 or croak 'usage: $nntp->quit()';
 347    my $nntp = shift;
 348  
 349    $nntp->_QUIT;
 350    $nntp->close;
 351  }
 352  
 353  
 354  sub slave {
 355    @_ == 1 or croak 'usage: $nntp->slave()';
 356    my $nntp = shift;
 357  
 358    $nntp->_SLAVE;
 359  }
 360  
 361  ##
 362  ## The following methods are not implemented by all servers
 363  ##
 364  
 365  
 366  sub active {
 367    @_ == 1 || @_ == 2 or croak 'usage: $nntp->active( [ PATTERN ] )';
 368    my $nntp = shift;
 369  
 370    $nntp->_LIST('ACTIVE', @_)
 371      ? $nntp->_grouplist
 372      : undef;
 373  }
 374  
 375  
 376  sub active_times {
 377    @_ == 1 or croak 'usage: $nntp->active_times()';
 378    my $nntp = shift;
 379  
 380    $nntp->_LIST('ACTIVE.TIMES')
 381      ? $nntp->_grouplist
 382      : undef;
 383  }
 384  
 385  
 386  sub distributions {
 387    @_ == 1 or croak 'usage: $nntp->distributions()';
 388    my $nntp = shift;
 389  
 390    $nntp->_LIST('DISTRIBUTIONS')
 391      ? $nntp->_description
 392      : undef;
 393  }
 394  
 395  
 396  sub distribution_patterns {
 397    @_ == 1 or croak 'usage: $nntp->distributions()';
 398    my $nntp = shift;
 399  
 400    my $arr;
 401    local $_;
 402  
 403    $nntp->_LIST('DISTRIB.PATS')
 404      && ($arr = $nntp->read_until_dot)
 405      ? [grep { /^\d/ && (chomp, $_ = [split /:/]) } @$arr]
 406      : undef;
 407  }
 408  
 409  
 410  sub newsgroups {
 411    @_ == 1 || @_ == 2 or croak 'usage: $nntp->newsgroups( [ PATTERN ] )';
 412    my $nntp = shift;
 413  
 414    $nntp->_LIST('NEWSGROUPS', @_)
 415      ? $nntp->_description
 416      : undef;
 417  }
 418  
 419  
 420  sub overview_fmt {
 421    @_ == 1 or croak 'usage: $nntp->overview_fmt()';
 422    my $nntp = shift;
 423  
 424    $nntp->_LIST('OVERVIEW.FMT')
 425      ? $nntp->_articlelist
 426      : undef;
 427  }
 428  
 429  
 430  sub subscriptions {
 431    @_ == 1 or croak 'usage: $nntp->subscriptions()';
 432    my $nntp = shift;
 433  
 434    $nntp->_LIST('SUBSCRIPTIONS')
 435      ? $nntp->_articlelist
 436      : undef;
 437  }
 438  
 439  
 440  sub listgroup {
 441    @_ == 1 || @_ == 2 or croak 'usage: $nntp->listgroup( [ GROUP ] )';
 442    my $nntp = shift;
 443  
 444    $nntp->_LISTGROUP(@_)
 445      ? $nntp->_articlelist
 446      : undef;
 447  }
 448  
 449  
 450  sub reader {
 451    @_ == 1 or croak 'usage: $nntp->reader()';
 452    my $nntp = shift;
 453  
 454    $nntp->_MODE('READER');
 455  }
 456  
 457  
 458  sub xgtitle {
 459    @_ == 1 || @_ == 2 or croak 'usage: $nntp->xgtitle( [ PATTERN ] )';
 460    my $nntp = shift;
 461  
 462    $nntp->_XGTITLE(@_)
 463      ? $nntp->_description
 464      : undef;
 465  }
 466  
 467  
 468  sub xhdr {
 469    @_ >= 2 && @_ <= 4 or croak 'usage: $nntp->xhdr( HEADER, [ MESSAGE-SPEC ] )';
 470    my $nntp = shift;
 471    my $hdr  = shift;
 472    my $arg  = _msg_arg(@_);
 473  
 474    $nntp->_XHDR($hdr, $arg)
 475      ? $nntp->_description
 476      : undef;
 477  }
 478  
 479  
 480  sub xover {
 481    @_ == 2 || @_ == 3 or croak 'usage: $nntp->xover( MESSAGE-SPEC )';
 482    my $nntp = shift;
 483    my $arg  = _msg_arg(@_);
 484  
 485    $nntp->_XOVER($arg)
 486      ? $nntp->_fieldlist
 487      : undef;
 488  }
 489  
 490  
 491  sub xpat {
 492    @_ == 4 || @_ == 5 or croak '$nntp->xpat( HEADER, PATTERN, MESSAGE-SPEC )';
 493    my $nntp = shift;
 494    my $hdr  = shift;
 495    my $pat  = shift;
 496    my $arg  = _msg_arg(@_);
 497  
 498    $pat = join(" ", @$pat)
 499      if ref($pat);
 500  
 501    $nntp->_XPAT($hdr, $arg, $pat)
 502      ? $nntp->_description
 503      : undef;
 504  }
 505  
 506  
 507  sub xpath {
 508    @_ == 2 or croak 'usage: $nntp->xpath( MESSAGE-ID )';
 509    my ($nntp, $mid) = @_;
 510  
 511    return undef
 512      unless $nntp->_XPATH($mid);
 513  
 514    my $m;
 515    ($m = $nntp->message) =~ s/^\d+\s+//o;
 516    my @p = split /\s+/, $m;
 517  
 518    wantarray ? @p : $p[0];
 519  }
 520  
 521  
 522  sub xrover {
 523    @_ == 2 || @_ == 3 or croak 'usage: $nntp->xrover( MESSAGE-SPEC )';
 524    my $nntp = shift;
 525    my $arg  = _msg_arg(@_);
 526  
 527    $nntp->_XROVER($arg)
 528      ? $nntp->_description
 529      : undef;
 530  }
 531  
 532  
 533  sub date {
 534    @_ == 1 or croak 'usage: $nntp->date()';
 535    my $nntp = shift;
 536  
 537    $nntp->_DATE
 538      && $nntp->message =~ /(\d{4})(\d\d)(\d\d)(\d\d)(\d\d)(\d\d)/
 539      ? timegm($6, $5, $4, $3, $2 - 1, $1 - 1900)
 540      : undef;
 541  }
 542  
 543  
 544  ##
 545  ## Private subroutines
 546  ##
 547  
 548  
 549  sub _msg_arg {
 550    my $spec = shift;
 551    my $arg  = "";
 552  
 553    if (@_) {
 554      carp "Depriciated passing of two message numbers, " . "pass a reference"
 555        if $^W;
 556      $spec = [$spec, $_[0]];
 557    }
 558  
 559    if (defined $spec) {
 560      if (ref($spec)) {
 561        $arg = $spec->[0];
 562        if (defined $spec->[1]) {
 563          $arg .= "-"
 564            if $spec->[1] != $spec->[0];
 565          $arg .= $spec->[1]
 566            if $spec->[1] > $spec->[0];
 567        }
 568      }
 569      else {
 570        $arg = $spec;
 571      }
 572    }
 573  
 574    $arg;
 575  }
 576  
 577  
 578  sub _timestr {
 579    my $time = shift;
 580    my @g    = reverse((gmtime($time))[0 .. 5]);
 581    $g[1] += 1;
 582    $g[0] %= 100;
 583    sprintf "%02d%02d%02d %02d%02d%02d GMT", @g;
 584  }
 585  
 586  
 587  sub _grouplist {
 588    my $nntp = shift;
 589    my $arr  = $nntp->read_until_dot
 590      or return undef;
 591  
 592    my $hash = {};
 593    my $ln;
 594  
 595    foreach $ln (@$arr) {
 596      my @a = split(/[\s\n]+/, $ln);
 597      $hash->{$a[0]} = [@a[1, 2, 3]];
 598    }
 599  
 600    $hash;
 601  }
 602  
 603  
 604  sub _fieldlist {
 605    my $nntp = shift;
 606    my $arr  = $nntp->read_until_dot
 607      or return undef;
 608  
 609    my $hash = {};
 610    my $ln;
 611  
 612    foreach $ln (@$arr) {
 613      my @a = split(/[\t\n]/, $ln);
 614      my $m = shift @a;
 615      $hash->{$m} = [@a];
 616    }
 617  
 618    $hash;
 619  }
 620  
 621  
 622  sub _articlelist {
 623    my $nntp = shift;
 624    my $arr  = $nntp->read_until_dot;
 625  
 626    chomp(@$arr)
 627      if $arr;
 628  
 629    $arr;
 630  }
 631  
 632  
 633  sub _description {
 634    my $nntp = shift;
 635    my $arr  = $nntp->read_until_dot
 636      or return undef;
 637  
 638    my $hash = {};
 639    my $ln;
 640  
 641    foreach $ln (@$arr) {
 642      chomp($ln);
 643  
 644      $hash->{$1} = $ln
 645        if $ln =~ s/^\s*(\S+)\s*//o;
 646    }
 647  
 648    $hash;
 649  
 650  }
 651  
 652  ##
 653  ## The commands
 654  ##
 655  
 656  
 657  sub _ARTICLE  { shift->command('ARTICLE',  @_)->response == CMD_OK }
 658  sub _AUTHINFO { shift->command('AUTHINFO', @_)->response }
 659  sub _BODY     { shift->command('BODY',     @_)->response == CMD_OK }
 660  sub _DATE      { shift->command('DATE')->response == CMD_INFO }
 661  sub _GROUP     { shift->command('GROUP', @_)->response == CMD_OK }
 662  sub _HEAD      { shift->command('HEAD', @_)->response == CMD_OK }
 663  sub _HELP      { shift->command('HELP', @_)->response == CMD_INFO }
 664  sub _IHAVE     { shift->command('IHAVE', @_)->response == CMD_MORE }
 665  sub _LAST      { shift->command('LAST')->response == CMD_OK }
 666  sub _LIST      { shift->command('LIST', @_)->response == CMD_OK }
 667  sub _LISTGROUP { shift->command('LISTGROUP', @_)->response == CMD_OK }
 668  sub _NEWGROUPS { shift->command('NEWGROUPS', @_)->response == CMD_OK }
 669  sub _NEWNEWS   { shift->command('NEWNEWS', @_)->response == CMD_OK }
 670  sub _NEXT      { shift->command('NEXT')->response == CMD_OK }
 671  sub _POST      { shift->command('POST', @_)->response == CMD_MORE }
 672  sub _QUIT      { shift->command('QUIT', @_)->response == CMD_OK }
 673  sub _SLAVE     { shift->command('SLAVE', @_)->response == CMD_OK }
 674  sub _STAT      { shift->command('STAT', @_)->response == CMD_OK }
 675  sub _MODE      { shift->command('MODE', @_)->response == CMD_OK }
 676  sub _XGTITLE   { shift->command('XGTITLE', @_)->response == CMD_OK }
 677  sub _XHDR      { shift->command('XHDR', @_)->response == CMD_OK }
 678  sub _XPAT      { shift->command('XPAT', @_)->response == CMD_OK }
 679  sub _XPATH     { shift->command('XPATH', @_)->response == CMD_OK }
 680  sub _XOVER     { shift->command('XOVER', @_)->response == CMD_OK }
 681  sub _XROVER    { shift->command('XROVER', @_)->response == CMD_OK }
 682  sub _XTHREAD   { shift->unsupported }
 683  sub _XSEARCH   { shift->unsupported }
 684  sub _XINDEX    { shift->unsupported }
 685  
 686  ##
 687  ## IO/perl methods
 688  ##
 689  
 690  
 691  sub DESTROY {
 692    my $nntp = shift;
 693    defined(fileno($nntp)) && $nntp->quit;
 694  }
 695  
 696  
 697  1;
 698  
 699  __END__
 700  
 701  =head1 NAME
 702  
 703  Net::NNTP - NNTP Client class
 704  
 705  =head1 SYNOPSIS
 706  
 707      use Net::NNTP;
 708  
 709      $nntp = Net::NNTP->new("some.host.name");
 710      $nntp->quit;
 711  
 712  =head1 DESCRIPTION
 713  
 714  C<Net::NNTP> is a class implementing a simple NNTP client in Perl as described
 715  in RFC977. C<Net::NNTP> inherits its communication methods from C<Net::Cmd>
 716  
 717  =head1 CONSTRUCTOR
 718  
 719  =over 4
 720  
 721  =item new ( [ HOST ] [, OPTIONS ])
 722  
 723  This is the constructor for a new Net::NNTP object. C<HOST> is the
 724  name of the remote host to which a NNTP connection is required. If not
 725  given then it may be passed as the C<Host> option described below. If no host is passed
 726  then two environment variables are checked, first C<NNTPSERVER> then
 727  C<NEWSHOST>, then C<Net::Config> is checked, and if a host is not found
 728  then C<news> is used.
 729  
 730  C<OPTIONS> are passed in a hash like fashion, using key and value pairs.
 731  Possible options are:
 732  
 733  B<Host> - NNTP host to connect to. It may be a single scalar, as defined for
 734  the C<PeerAddr> option in L<IO::Socket::INET>, or a reference to
 735  an array with hosts to try in turn. The L</host> method will return the value
 736  which was used to connect to the host.
 737  
 738  B<Timeout> - Maximum time, in seconds, to wait for a response from the
 739  NNTP server, a value of zero will cause all IO operations to block.
 740  (default: 120)
 741  
 742  B<Debug> - Enable the printing of debugging information to STDERR
 743  
 744  B<Reader> - If the remote server is INN then initially the connection
 745  will be to nnrpd, by default C<Net::NNTP> will issue a C<MODE READER> command
 746  so that the remote server becomes innd. If the C<Reader> option is given
 747  with a value of zero, then this command will not be sent and the
 748  connection will be left talking to nnrpd.
 749  
 750  =back
 751  
 752  =head1 METHODS
 753  
 754  Unless otherwise stated all methods return either a I<true> or I<false>
 755  value, with I<true> meaning that the operation was a success. When a method
 756  states that it returns a value, failure will be returned as I<undef> or an
 757  empty list.
 758  
 759  =over 4
 760  
 761  =item article ( [ MSGID|MSGNUM ], [FH] )
 762  
 763  Retrieve the header, a blank line, then the body (text) of the
 764  specified article. 
 765  
 766  If C<FH> is specified then it is expected to be a valid filehandle
 767  and the result will be printed to it, on success a true value will be
 768  returned. If C<FH> is not specified then the return value, on success,
 769  will be a reference to an array containing the article requested, each
 770  entry in the array will contain one line of the article.
 771  
 772  If no arguments are passed then the current article in the currently
 773  selected newsgroup is fetched.
 774  
 775  C<MSGNUM> is a numeric id of an article in the current newsgroup, and
 776  will change the current article pointer.  C<MSGID> is the message id of
 777  an article as shown in that article's header.  It is anticipated that the
 778  client will obtain the C<MSGID> from a list provided by the C<newnews>
 779  command, from references contained within another article, or from the
 780  message-id provided in the response to some other commands.
 781  
 782  If there is an error then C<undef> will be returned.
 783  
 784  =item body ( [ MSGID|MSGNUM ], [FH] )
 785  
 786  Like C<article> but only fetches the body of the article.
 787  
 788  =item head ( [ MSGID|MSGNUM ], [FH] )
 789  
 790  Like C<article> but only fetches the headers for the article.
 791  
 792  =item articlefh ( [ MSGID|MSGNUM ] )
 793  
 794  =item bodyfh ( [ MSGID|MSGNUM ] )
 795  
 796  =item headfh ( [ MSGID|MSGNUM ] )
 797  
 798  These are similar to article(), body() and head(), but rather than
 799  returning the requested data directly, they return a tied filehandle
 800  from which to read the article.
 801  
 802  =item nntpstat ( [ MSGID|MSGNUM ] )
 803  
 804  The C<nntpstat> command is similar to the C<article> command except that no
 805  text is returned.  When selecting by message number within a group,
 806  the C<nntpstat> command serves to set the "current article pointer" without
 807  sending text.
 808  
 809  Using the C<nntpstat> command to
 810  select by message-id is valid but of questionable value, since a
 811  selection by message-id does B<not> alter the "current article pointer".
 812  
 813  Returns the message-id of the "current article".
 814  
 815  =item group ( [ GROUP ] )
 816  
 817  Set and/or get the current group. If C<GROUP> is not given then information
 818  is returned on the current group.
 819  
 820  In a scalar context it returns the group name.
 821  
 822  In an array context the return value is a list containing, the number
 823  of articles in the group, the number of the first article, the number
 824  of the last article and the group name.
 825  
 826  =item ihave ( MSGID [, MESSAGE ])
 827  
 828  The C<ihave> command informs the server that the client has an article
 829  whose id is C<MSGID>.  If the server desires a copy of that
 830  article, and C<MESSAGE> has been given the it will be sent.
 831  
 832  Returns I<true> if the server desires the article and C<MESSAGE> was
 833  successfully sent,if specified.
 834  
 835  If C<MESSAGE> is not specified then the message must be sent using the
 836  C<datasend> and C<dataend> methods from L<Net::Cmd>
 837  
 838  C<MESSAGE> can be either an array of lines or a reference to an array.
 839  
 840  =item last ()
 841  
 842  Set the "current article pointer" to the previous article in the current
 843  newsgroup.
 844  
 845  Returns the message-id of the article.
 846  
 847  =item date ()
 848  
 849  Returns the date on the remote server. This date will be in a UNIX time
 850  format (seconds since 1970)
 851  
 852  =item postok ()
 853  
 854  C<postok> will return I<true> if the servers initial response indicated
 855  that it will allow posting.
 856  
 857  =item authinfo ( USER, PASS )
 858  
 859  Authenticates to the server (using AUTHINFO USER / AUTHINFO PASS)
 860  using the supplied username and password.  Please note that the
 861  password is sent in clear text to the server.  This command should not
 862  be used with valuable passwords unless the connection to the server is
 863  somehow protected.
 864  
 865  =item list ()
 866  
 867  Obtain information about all the active newsgroups. The results is a reference
 868  to a hash where the key is a group name and each value is a reference to an
 869  array. The elements in this array are:- the last article number in the group,
 870  the first article number in the group and any information flags about the group.
 871  
 872  =item newgroups ( SINCE [, DISTRIBUTIONS ])
 873  
 874  C<SINCE> is a time value and C<DISTRIBUTIONS> is either a distribution
 875  pattern or a reference to a list of distribution patterns.
 876  The result is the same as C<list>, but the
 877  groups return will be limited to those created after C<SINCE> and, if
 878  specified, in one of the distribution areas in C<DISTRIBUTIONS>. 
 879  
 880  =item newnews ( SINCE [, GROUPS [, DISTRIBUTIONS ]])
 881  
 882  C<SINCE> is a time value. C<GROUPS> is either a group pattern or a reference
 883  to a list of group patterns. C<DISTRIBUTIONS> is either a distribution
 884  pattern or a reference to a list of distribution patterns.
 885  
 886  Returns a reference to a list which contains the message-ids of all news posted
 887  after C<SINCE>, that are in a groups which matched C<GROUPS> and a
 888  distribution which matches C<DISTRIBUTIONS>.
 889  
 890  =item next ()
 891  
 892  Set the "current article pointer" to the next article in the current
 893  newsgroup.
 894  
 895  Returns the message-id of the article.
 896  
 897  =item post ( [ MESSAGE ] )
 898  
 899  Post a new article to the news server. If C<MESSAGE> is specified and posting
 900  is allowed then the message will be sent.
 901  
 902  If C<MESSAGE> is not specified then the message must be sent using the
 903  C<datasend> and C<dataend> methods from L<Net::Cmd>
 904  
 905  C<MESSAGE> can be either an array of lines or a reference to an array.
 906  
 907  The message, either sent via C<datasend> or as the C<MESSAGE>
 908  parameter, must be in the format as described by RFC822 and must
 909  contain From:, Newsgroups: and Subject: headers.
 910  
 911  =item postfh ()
 912  
 913  Post a new article to the news server using a tied filehandle.  If
 914  posting is allowed, this method will return a tied filehandle that you
 915  can print() the contents of the article to be posted.  You must
 916  explicitly close() the filehandle when you are finished posting the
 917  article, and the return value from the close() call will indicate
 918  whether the message was successfully posted.
 919  
 920  =item slave ()
 921  
 922  Tell the remote server that I am not a user client, but probably another
 923  news server.
 924  
 925  =item quit ()
 926  
 927  Quit the remote server and close the socket connection.
 928  
 929  =back
 930  
 931  =head2 Extension methods
 932  
 933  These methods use commands that are not part of the RFC977 documentation. Some
 934  servers may not support all of them.
 935  
 936  =over 4
 937  
 938  =item newsgroups ( [ PATTERN ] )
 939  
 940  Returns a reference to a hash where the keys are all the group names which
 941  match C<PATTERN>, or all of the groups if no pattern is specified, and
 942  each value contains the description text for the group.
 943  
 944  =item distributions ()
 945  
 946  Returns a reference to a hash where the keys are all the possible
 947  distribution names and the values are the distribution descriptions.
 948  
 949  =item subscriptions ()
 950  
 951  Returns a reference to a list which contains a list of groups which
 952  are recommended for a new user to subscribe to.
 953  
 954  =item overview_fmt ()
 955  
 956  Returns a reference to an array which contain the names of the fields returned
 957  by C<xover>.
 958  
 959  =item active_times ()
 960  
 961  Returns a reference to a hash where the keys are the group names and each
 962  value is a reference to an array containing the time the groups was created
 963  and an identifier, possibly an Email address, of the creator.
 964  
 965  =item active ( [ PATTERN ] )
 966  
 967  Similar to C<list> but only active groups that match the pattern are returned.
 968  C<PATTERN> can be a group pattern.
 969  
 970  =item xgtitle ( PATTERN )
 971  
 972  Returns a reference to a hash where the keys are all the group names which
 973  match C<PATTERN> and each value is the description text for the group.
 974  
 975  =item xhdr ( HEADER, MESSAGE-SPEC )
 976  
 977  Obtain the header field C<HEADER> for all the messages specified. 
 978  
 979  The return value will be a reference
 980  to a hash where the keys are the message numbers and each value contains
 981  the text of the requested header for that message.
 982  
 983  =item xover ( MESSAGE-SPEC )
 984  
 985  The return value will be a reference
 986  to a hash where the keys are the message numbers and each value contains
 987  a reference to an array which contains the overview fields for that
 988  message.
 989  
 990  The names of the fields can be obtained by calling C<overview_fmt>.
 991  
 992  =item xpath ( MESSAGE-ID )
 993  
 994  Returns the path name to the file on the server which contains the specified
 995  message.
 996  
 997  =item xpat ( HEADER, PATTERN, MESSAGE-SPEC)
 998  
 999  The result is the same as C<xhdr> except the is will be restricted to
1000  headers where the text of the header matches C<PATTERN>
1001  
1002  =item xrover
1003  
1004  The XROVER command returns reference information for the article(s)
1005  specified.
1006  
1007  Returns a reference to a HASH where the keys are the message numbers and the
1008  values are the References: lines from the articles
1009  
1010  =item listgroup ( [ GROUP ] )
1011  
1012  Returns a reference to a list of all the active messages in C<GROUP>, or
1013  the current group if C<GROUP> is not specified.
1014  
1015  =item reader
1016  
1017  Tell the server that you are a reader and not another server.
1018  
1019  This is required by some servers. For example if you are connecting to
1020  an INN server and you have transfer permission your connection will
1021  be connected to the transfer daemon, not the NNTP daemon. Issuing
1022  this command will cause the transfer daemon to hand over control
1023  to the NNTP daemon.
1024  
1025  Some servers do not understand this command, but issuing it and ignoring
1026  the response is harmless.
1027  
1028  =back
1029  
1030  =head1 UNSUPPORTED
1031  
1032  The following NNTP command are unsupported by the package, and there are
1033  no plans to do so.
1034  
1035      AUTHINFO GENERIC
1036      XTHREAD
1037      XSEARCH
1038      XINDEX
1039  
1040  =head1 DEFINITIONS
1041  
1042  =over 4
1043  
1044  =item MESSAGE-SPEC
1045  
1046  C<MESSAGE-SPEC> is either a single message-id, a single message number, or
1047  a reference to a list of two message numbers.
1048  
1049  If C<MESSAGE-SPEC> is a reference to a list of two message numbers and the
1050  second number in a range is less than or equal to the first then the range
1051  represents all messages in the group after the first message number.
1052  
1053  B<NOTE> For compatibility reasons only with earlier versions of Net::NNTP
1054  a message spec can be passed as a list of two numbers, this is deprecated
1055  and a reference to the list should now be passed
1056  
1057  =item PATTERN
1058  
1059  The C<NNTP> protocol uses the C<WILDMAT> format for patterns.
1060  The WILDMAT format was first developed by Rich Salz based on
1061  the format used in the UNIX "find" command to articulate
1062  file names. It was developed to provide a uniform mechanism
1063  for matching patterns in the same manner that the UNIX shell
1064  matches filenames.
1065  
1066  Patterns are implicitly anchored at the
1067  beginning and end of each string when testing for a match.
1068  
1069  There are five pattern matching operations other than a strict
1070  one-to-one match between the pattern and the source to be
1071  checked for a match.
1072  
1073  The first is an asterisk C<*> to match any sequence of zero or more
1074  characters.
1075  
1076  The second is a question mark C<?> to match any single character. The
1077  third specifies a specific set of characters.
1078  
1079  The set is specified as a list of characters, or as a range of characters
1080  where the beginning and end of the range are separated by a minus (or dash)
1081  character, or as any combination of lists and ranges. The dash can
1082  also be included in the set as a character it if is the beginning
1083  or end of the set. This set is enclosed in square brackets. The
1084  close square bracket C<]> may be used in a set if it is the first
1085  character in the set.
1086  
1087  The fourth operation is the same as the
1088  logical not of the third operation and is specified the same
1089  way as the third with the addition of a caret character C<^> at
1090  the beginning of the test string just inside the open square
1091  bracket.
1092  
1093  The final operation uses the backslash character to
1094  invalidate the special meaning of an open square bracket C<[>,
1095  the asterisk, backslash or the question mark. Two backslashes in
1096  sequence will result in the evaluation of the backslash as a
1097  character with no special meaning.
1098  
1099  =over 4
1100  
1101  =item Examples
1102  
1103  =item C<[^]-]>
1104  
1105  matches any single character other than a close square
1106  bracket or a minus sign/dash.
1107  
1108  =item C<*bdc>
1109  
1110  matches any string that ends with the string "bdc"
1111  including the string "bdc" (without quotes).
1112  
1113  =item C<[0-9a-zA-Z]>
1114  
1115  matches any single printable alphanumeric ASCII character.
1116  
1117  =item C<a??d>
1118  
1119  matches any four character string which begins
1120  with a and ends with d.
1121  
1122  =back
1123  
1124  =back
1125  
1126  =head1 SEE ALSO
1127  
1128  L<Net::Cmd>
1129  
1130  =head1 AUTHOR
1131  
1132  Graham Barr <gbarr@pobox.com>
1133  
1134  =head1 COPYRIGHT
1135  
1136  Copyright (c) 1995-1997 Graham Barr. All rights reserved.
1137  This program is free software; you can redistribute it and/or modify
1138  it under the same terms as Perl itself.
1139  
1140  =cut


Generated: Tue Mar 17 22:47:18 2015 Cross-referenced by PHPXref 0.7.1