home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-perl-addon-1.4.9-installer.exe / POP3Client.pm < prev    next >
Encoding:
Perl POD Document  |  2003-10-18  |  42.3 KB  |  1,512 lines
  1. #******************************************************************************
  2. # $Id: POP3Client.pm,v 2.15 2003/10/18 23:12:46 ssd Exp $
  3. #
  4. # Description:  POP3Client module - acts as interface to POP3 server
  5. # Author:       Sean Dowd <pop3client@dowds.net>
  6. #
  7. # Copyright (c) 1999-2003  Sean Dowd.  All rights reserved.
  8. # This module is free software; you can redistribute it and/or modify
  9. # it under the same terms as Perl itself.
  10. #
  11. #******************************************************************************
  12.  
  13. package Mail::POP3Client;
  14.  
  15. use strict;
  16. use Carp;
  17. use IO::Socket qw(SOCK_STREAM);
  18.  
  19. use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
  20.  
  21. require Exporter;
  22.  
  23. @ISA = qw(Exporter);
  24. # Items to export into callers namespace by default. Note: do not export
  25. # names by default without a very good reason. Use EXPORT_OK instead.
  26. # Do not simply export all your public functions/methods/constants.
  27. @EXPORT = qw(
  28.  
  29. );
  30.  
  31. my $ID =q( $Id: POP3Client.pm,v 2.15 2003/10/18 23:12:46 ssd Exp $ );
  32. $VERSION = substr q$Revision: 2.15 $, 10;
  33.  
  34.  
  35. # Preloaded methods go here.
  36.  
  37. #******************************************************************************
  38. #* constructor
  39. #* new Mail::POP3Client( USER => user,
  40. #*                       PASSWORD => pass,
  41. #*                       HOST => host,
  42. #*                       AUTH_MODE => [BEST|APOP|CRAM-MD5|PASS],
  43. #*                       TIMEOUT => 30,
  44. #*                       LOCALADDR => 'xxx.xxx.xxx.xxx[:xx]',
  45. #*                       DEBUG => 1 );
  46. #* OR (deprecated)
  47. #* new Mail::POP3Client( user, pass, host [, port, debug, auth_mode, local_addr])
  48. #******************************************************************************
  49. sub new
  50. {
  51.   my $classname = shift;
  52.   my $self = {
  53.           DEBUG => 0,
  54.           SERVER => "pop3",
  55.           PORT => 110,
  56.           COUNT => -1,
  57.           SIZE => -1,
  58.           ADDR => "",
  59.           STATE => 'DEAD',
  60.           MESG => 'OK',
  61.           BANNER => '',
  62.           MESG_ID => '',
  63.           AUTH_MODE => 'BEST',
  64.           EOL => "\015\012",
  65.           TIMEOUT => 60,
  66.           STRIPCR => 0,
  67.           LOCALADDR => undef,
  68.           SOCKET => undef,
  69.           USESSL => 0,
  70.          };
  71.   $self->{tranlog} = ();
  72.   $^O =~ /MacOS/i && ($self->{STRIPCR} = 1);
  73.   bless( $self, $classname );
  74.   $self->_init( @_ );
  75.  
  76.   if ( defined($self->User()) && defined($self->Pass()) )
  77.     {
  78.       $self->Connect();
  79.     }
  80.  
  81.   return $self;
  82. }
  83.  
  84.  
  85.  
  86. #******************************************************************************
  87. #* initialize - check for old-style params
  88. #******************************************************************************
  89. sub _init {
  90.   my $self = shift;
  91.  
  92.   # if it looks like a hash
  93.   if ( @_ && (scalar( @_ ) % 2 == 0) )
  94.     {
  95.       # ... and smells like a hash...
  96.       my %hashargs = @_;
  97.       if ( ( defined($hashargs{USER}) &&
  98.          defined($hashargs{PASSWORD}) ) ||
  99.        defined($hashargs{HOST})
  100.      )
  101.     {
  102.       # ... then it must be a hash!  Push all values into my internal hash.
  103.       foreach my $key ( keys %hashargs )
  104.         {
  105.           $self->{$key} = $hashargs{$key};
  106.         }
  107.     }
  108.       else {$self->_initOldStyle( @_ );}
  109.     }
  110.   else {$self->_initOldStyle( @_ );}
  111. }
  112.  
  113. #******************************************************************************
  114. #* initialize using the old positional parameter style new - deprecated
  115. #******************************************************************************
  116. sub _initOldStyle {
  117.   my $self = shift;
  118.   $self->User( shift );
  119.   $self->Pass( shift );
  120.   my $host = shift;
  121.   $host && $self->Host( $host );
  122.   my $port = shift;
  123.   $port && $self->Port( $port );
  124.   my $debug = shift;
  125.   $debug && $self->Debug( $debug );
  126.   my $auth_mode = shift;
  127.   $auth_mode && ($self->{AUTH_MODE} = $auth_mode);
  128.   my $localaddr = shift;
  129.   $localaddr && ($self->{LOCALADDR} = $localaddr);
  130. }
  131.  
  132. #******************************************************************************
  133. #* What version are we?
  134. #******************************************************************************
  135. sub Version {
  136.   return $VERSION;
  137. }
  138.  
  139.  
  140. #******************************************************************************
  141. #* Is the socket alive?
  142. #******************************************************************************
  143. sub Alive
  144. {
  145.   my $me = shift;
  146.   $me->State =~ /^AUTHORIZATION$|^TRANSACTION$/i;
  147. } # end Alive
  148.  
  149.  
  150. #******************************************************************************
  151. #* What's the frequency Kenneth?
  152. #******************************************************************************
  153. sub State
  154. {
  155.   my $me = shift;
  156.   my $stat = shift or return $me->{STATE};
  157.   $me->{STATE} = $stat;
  158. } # end Stat
  159.  
  160.  
  161. #******************************************************************************
  162. #* Got anything to say?
  163. #******************************************************************************
  164. sub Message
  165. {
  166.   my $me = shift;
  167.   my $msg = shift or return $me->{MESG};
  168.   $me->{MESG} = $msg;
  169. } # end Message
  170.  
  171.  
  172. #******************************************************************************
  173. #* set/query debugging
  174. #******************************************************************************
  175. sub Debug
  176. {
  177.   my $me = shift;
  178.   my $debug = shift or return $me->{DEBUG};
  179.   $me->{DEBUG} = $debug;
  180.  
  181. } # end Debug
  182.  
  183.  
  184. #******************************************************************************
  185. #* set/query the port number
  186. #******************************************************************************
  187. sub Port
  188. {
  189.   my $me = shift;
  190.   my $port = shift or return $me->{PORT};
  191.  
  192.   $me->{PORT} = $port;
  193.  
  194. } # end port
  195.  
  196.  
  197. #******************************************************************************
  198. #* set the host
  199. #******************************************************************************
  200. sub Host
  201. {
  202.   my $me = shift;
  203.   my $host = shift or return $me->{HOST};
  204.  
  205. #  $me->{INTERNET_ADDR} = inet_aton( $host ) or
  206. #    $me->Message( "Could not inet_aton: $host, $!") and return;
  207.   $me->{HOST} = $host;
  208. } # end host
  209.  
  210. #******************************************************************************
  211. #* set the local address
  212. #******************************************************************************
  213. sub LocalAddr
  214. {
  215.   my $me = shift;
  216.   my $addr = shift or return $me->{LOCALADDR};
  217.  
  218.   $me->{LOCALADDR} = $addr;
  219. }
  220.  
  221.  
  222. #******************************************************************************
  223. #* query the socket to use as a file handle - allows you to set the
  224. #* socket too to allow SSL (thanks to Jamie LeTual)
  225. #******************************************************************************
  226. sub Socket {
  227.   my $me = shift;
  228.   my $socket = shift or return $me->{'SOCKET'};
  229.   $me->{'SOCKET'} = $socket;
  230. }
  231.  
  232. sub AuthMode {
  233.   my $me = shift;
  234.   my $mode = shift;
  235.   return $me->{'AUTH_MODE'} unless $mode;
  236.   $me->{'AUTH_MODE'} = $mode;
  237. }
  238.  
  239. #******************************************************************************
  240. #* set/query the USER
  241. #******************************************************************************
  242. sub User
  243. {
  244.   my $me = shift;
  245.   my $user = shift or return $me->{USER};
  246.   $me->{USER} = $user;
  247.  
  248. } # end User
  249.  
  250.  
  251. #******************************************************************************
  252. #* set/query the password
  253. #******************************************************************************
  254. sub Pass
  255. {
  256.   my $me = shift;
  257.   my $pass = shift or return $me->{PASSWORD};
  258.   $me->{PASSWORD} = $pass;
  259.  
  260. } # end Pass
  261.  
  262. sub Password { Pass(@_); }
  263.  
  264. #******************************************************************************
  265. #*
  266. #******************************************************************************
  267. sub Count
  268. {
  269.   my $me = shift;
  270.   my $c = shift;
  271.   if (defined $c and length($c) > 0) {
  272.     $me->{COUNT} = $c;
  273.   } else {
  274.     return $me->{COUNT};
  275.   }
  276.  
  277. } # end Count
  278.  
  279.  
  280. #******************************************************************************
  281. #* set/query the size of the mailbox
  282. #******************************************************************************
  283. sub Size
  284. {
  285.   my $me = shift;
  286.   my $c = shift;
  287.   if (defined $c and length($c) > 0) {
  288.     $me->{SIZE} = $c;
  289.   } else {
  290.     return $me->{SIZE};
  291.   }
  292.  
  293. } # end Size
  294.  
  295.  
  296. #******************************************************************************
  297. #*
  298. #******************************************************************************
  299. sub EOL {
  300.   my $me = shift;
  301.   return $me->{'EOL'};
  302. }
  303.  
  304.  
  305. #******************************************************************************
  306. #*
  307. #******************************************************************************
  308. sub Close
  309. {
  310.   my $me = shift;
  311.  
  312.   # only send the QUIT message is the socket is still connected.  Some
  313.   # POP3 servers close the socket after a failed authentication.  It
  314.   # is unclear whether the RFC allows this or not, so we'll attempt to
  315.   # check the condition of the socket before sending data here.
  316.   if ($me->Alive() && $me->Socket() && $me->Socket()->connected() ) {
  317.     $me->_sockprint( "QUIT", $me->EOL );
  318.  
  319.     # from Patrick Bourdon - need this because some servers do not
  320.     # delete in all cases.  RFC says server can respond (in UPDATE
  321.     # state only, otherwise always OK).
  322.     my $line = $me->_sockread();
  323.     unless (defined $line) {
  324.     $me->Message("Socket read failed for QUIT");
  325.     # XXX: Should add the following?
  326.     #$me->State('DEAD');
  327.     return 0;
  328.     }
  329.     $me->Message( $line );
  330.     close( $me->Socket() ) or $me->Message("close failed: $!") and return 0;
  331.     $me->State('DEAD');
  332.     $line =~ /^\+OK/i || return 0;
  333.   }
  334.   1;
  335. } # end Close
  336.  
  337. sub close { Close(@_); }
  338. sub logout { Close(@_); }
  339.  
  340. #******************************************************************************
  341. #*
  342. #******************************************************************************
  343. sub DESTROY
  344. {
  345.   my $me = shift;
  346.   $me->Close;
  347. } # end DESTROY
  348.  
  349.  
  350. #******************************************************************************
  351. #* Connect to the specified POP server
  352. #******************************************************************************
  353. sub Connect
  354. {
  355.   my ($me, $host, $port) = @_;
  356.  
  357.   $host and $me->Host($host);
  358.   $port and $me->Port($port);
  359.  
  360.   $me->Close();
  361.  
  362.   my $s = $me->{SOCKET};
  363.   $s || do {
  364.     if ( $me->{USESSL} ) {
  365.       if ( $me->Port() == 110 ) { $me->Port( 995 ); }
  366.         eval {
  367.       require IO::Socket::SSL;
  368.     };
  369.       $s = IO::Socket::SSL->new( PeerAddr => $me->Host(),
  370.                  PeerPort => $me->Port(),
  371.                  Proto    => "tcp",
  372.                  Type      => SOCK_STREAM,
  373.                  LocalAddr => $me->LocalAddr(),
  374.                  Timeout   => $me->{TIMEOUT} )
  375.     or $me->Message( "could not connect SSL socket [$me->{HOST}, $me->{PORT}]: $!" )
  376.       and return 0;
  377.       $me->{SOCKET} = $s;
  378.       
  379.     } else {
  380.       $s = IO::Socket::INET->new( PeerAddr  => $me->Host(),
  381.                   PeerPort  => $me->Port(),
  382.                   Proto     => "tcp",
  383.                   Type      => SOCK_STREAM,
  384.                   LocalAddr => $me->LocalAddr(),
  385.                   Timeout   => $me->{TIMEOUT} )
  386.     or
  387.       $me->Message( "could not connect socket [$me->{HOST}, $me->{PORT}]: $!" )
  388.         and
  389.           return 0;
  390.       $me->{SOCKET} = $s;
  391.     }
  392.   };
  393.  
  394.   $s->autoflush( 1 );
  395.  
  396.   defined(my $msg = $me->_sockread()) or $me->Message("Could not read") and return 0;
  397.   chomp $msg;
  398.   $me->{BANNER}= $msg;
  399.  
  400.   # add check for servers that return -ERR on connect (not in RFC1939)
  401.   $me->Message($msg);
  402.   $msg =~ /^\+OK/i || return 0;
  403.  
  404.   $me->{MESG_ID}= $1 if ($msg =~ /(<[\w\d\-\.]+\@[\w\d\-\.]+>)/);
  405.   $me->Message($msg);
  406.  
  407.   $me->State('AUTHORIZATION');
  408.   defined($me->User()) and defined($me->Pass()) and $me->Login();
  409.  
  410. } # end Connect
  411.  
  412. sub connect { Connect(@_); }
  413.  
  414. #******************************************************************************
  415. #* login to the POP server. If the AUTH_MODE is set to BEST, and the server
  416. #* appears to support APOP, it will try APOP, if that fails, then it will try
  417. #* SASL CRAM-MD5 if the server appears to support it, and finally PASS.
  418. #* If the AUTH_MODE is set to APOP, and the server appears to support APOP, it
  419. #* will use APOP or it will fail to log in. Likewise, for AUTH_MODE CRAM-MD5,
  420. #* no PASS-fallback is made. Otherwise password is sent in clear text.
  421. #******************************************************************************
  422. sub Login
  423. {
  424.   my $me= shift;
  425.   return 1 if $me->State eq 'TRANSACTION';  # Already logged in
  426.  
  427.   if ($me->{AUTH_MODE} eq 'BEST') {
  428.     my $retval;
  429.     if ($me->{MESG_ID}) {
  430.       $retval = $me->Login_APOP();
  431.       return($retval) if ($me->State eq 'TRANSACTION');
  432.     }
  433.     my $has_cram_md5 = 0;
  434.     foreach my $capa ($me->Capa()) {
  435.       $capa =~ /^SASL.*?\sCRAM-MD5\b/ and $has_cram_md5 = 1 and last;
  436.     }
  437.     if ($has_cram_md5) {
  438.       $retval = $me->Login_CRAM_MD5();
  439.       return($retval) if ($me->State() eq 'TRANSACTION');
  440.     }
  441.   }
  442.   elsif ($me->{AUTH_MODE} eq 'APOP') {
  443.     return(0) if (!$me->{MESG_ID});   # fail if the server does not support APOP
  444.     return($me->Login_APOP());
  445.   }
  446.   elsif ($me->{AUTH_MODE} eq 'CRAM-MD5') {
  447.     return($me->Login_CRAM_MD5());
  448.   }
  449.   elsif ($me->{AUTH_MODE} ne 'PASS') {
  450.     $me->Message("Programing error. AUTH_MODE (".$me->{AUTH_MODE}.") not BEST | APOP | CRAM-MD5 | PASS.");
  451.     return(0);
  452.   }
  453.   return($me->Login_Pass());
  454. }
  455.  
  456. sub login { Login(@_); }
  457.  
  458. #******************************************************************************
  459. #* login to the POP server using APOP (md5) authentication.
  460. #******************************************************************************
  461. sub Login_APOP
  462. {
  463.   my $me = shift;
  464.  
  465.   eval {
  466.     require Digest::MD5;
  467.   };
  468.   $@ and $me->Message("APOP failed: $@") and return 0;
  469.  
  470.   my $hash = Digest::MD5::md5_hex($me->{MESG_ID} . $me->Pass());
  471.  
  472.   $me->_checkstate('AUTHORIZATION', 'APOP') or return 0;
  473.   $me->_sockprint( "APOP " , $me->User , ' ', $hash, $me->EOL );
  474.   my $line = $me->_sockread();
  475.   unless (defined $line) {
  476.       $me->Message("Socket read failed for APOP");
  477.       $me->State('AUTHORIZATION');
  478.       return 0;
  479.   }
  480.   chomp $line;
  481.   $me->Message($line);
  482.   $line =~ /^\+OK/ or $me->Message("APOP failed: $line") and return 0;
  483.   $me->State('TRANSACTION');
  484.  
  485.   $me->POPStat() or return 0;
  486. }
  487.  
  488.  
  489. #******************************************************************************
  490. #* login to the POP server using CRAM-MD5 (RFC 2195) authentication.
  491. #******************************************************************************
  492. sub Login_CRAM_MD5
  493. {
  494.   my $me = shift;
  495.  
  496.   eval {
  497.     require Digest::HMAC_MD5;
  498.     require MIME::Base64;
  499.   };
  500.   $@ and $me->Message("AUTH CRAM-MD5 failed: $@") and return 0;
  501.  
  502.   $me->_checkstate('AUTHORIZATION', 'AUTH') or return 0;
  503.   $me->_sockprint('AUTH CRAM-MD5', $me->EOL());
  504.   my $line = $me->_sockread();
  505.   chomp $line;
  506.   $me->Message($line);
  507.  
  508.   if ($line =~ /^\+ (.+)$/) {
  509.  
  510.     my $hmac =
  511.       Digest::HMAC_MD5::hmac_md5_hex(MIME::Base64::decode($1), $me->Pass());
  512.     (my $response = MIME::Base64::encode($me->User() . " $hmac")) =~ s/[\r\n]//g;
  513.     $me->_sockprint($response, $me->EOL());
  514.  
  515.     $line = $me->_sockread();
  516.     chomp $line;
  517.     $me->Message($line);
  518.     $line =~ /^\+OK/ or
  519.       $me->Message("AUTH CRAM-MD5 failed: $line") and return 0;
  520.  
  521.   } else {
  522.     $me->Message("AUTH CRAM-MD5 failed: $line") and return 0;
  523.   }
  524.  
  525.   $me->State('TRANSACTION');
  526.  
  527.   $me->POPStat() or return 0;
  528. }
  529.  
  530.  
  531. #******************************************************************************
  532. #* login to the POP server using simple (cleartext) authentication.
  533. #******************************************************************************
  534. sub Login_Pass
  535. {
  536.   my $me = shift;
  537.  
  538.   $me->_checkstate('AUTHORIZATION', 'USER') or return 0;
  539.   $me->_sockprint( "USER " , $me->User() , $me->EOL );
  540.   my $line = $me->_sockread();
  541.   unless (defined $line) {
  542.       $me->Message("Socket read failed for USER");
  543.       $me->State('AUTHORIZATION');
  544.       return 0;
  545.   }
  546.   chomp $line;
  547.   $me->Message($line);
  548.   $line =~ /^\+/ or $me->Message("USER failed: $line") and $me->State('AUTHORIZATION')
  549.     and return 0;
  550.   
  551.   $me->_sockprint( "PASS " , $me->Pass() , $me->EOL );
  552.   $line = $me->_sockread();
  553.   unless (defined $line) {
  554.       $me->Message("Socket read failed for PASS");
  555.       $me->State('AUTHORIZATION');
  556.       return 0;
  557.   }
  558.   chomp $line;
  559.   $me->Message($line);
  560.   $line =~ /^\+OK/ or $me->Message("PASS failed: $line") and $me->State('AUTHORIZATION')
  561.     and return 0;
  562.   
  563.   $me->State('TRANSACTION');
  564.  
  565.   ($me->POPStat() >= 0) or return 0;
  566.  
  567. } # end Login
  568.  
  569.  
  570. #******************************************************************************
  571. #* Get the Head of a message number.  If you give an optional number
  572. #* of lines you will get the first n lines of the body also.  This
  573. #* allows you to preview a message.
  574. #******************************************************************************
  575. sub Head
  576. {
  577.   my $me = shift;
  578.   my $num = shift;
  579.   my $lines = shift;
  580.   $lines ||= 0;
  581.   $lines =~ /\d+/ || ($lines = 0);
  582.  
  583.   my $header = '';
  584.  
  585.   $me->_checkstate('TRANSACTION', 'TOP') or return;
  586.   $me->_sockprint( "TOP $num $lines", $me->EOL );
  587.   my $line = $me->_sockread();
  588.   unless (defined $line) {
  589.       $me->Message("Socket read failed for TOP");
  590.       return;
  591.   }
  592.   chomp $line;
  593.   $line =~ /^\+OK/ or $me->Message("Bad return from TOP: $line") and return;
  594.   $line =~ /^\+OK (\d+) / and my $buflen = $1;
  595.  
  596.   while (1) {
  597.     $line = $me->_sockread();
  598.     unless (defined $line) {
  599.     $me->Message("Socket read failed for TOP");
  600.     return;
  601.     }
  602.     last if $line =~ /^\.\s*$/;
  603.     $line =~ s/^\.\././;
  604.     $header .= $line;
  605.   }
  606.  
  607.   return wantarray ? split(/\r?\n/, $header) : $header;
  608. } # end Head
  609.  
  610.  
  611. #******************************************************************************
  612. #* Get the header and body of a message
  613. #******************************************************************************
  614. sub HeadAndBody
  615. {
  616.   my $me = shift;
  617.   my $num = shift;
  618.   my $mandb = '';
  619.  
  620.   $me->_checkstate('TRANSACTION', 'RETR') or return;
  621.   $me->_sockprint( "RETR $num", $me->EOL );
  622.   my $line = $me->_sockread();
  623.   unless (defined $line) {
  624.       $me->Message("Socket read failed for RETR");
  625.       return;
  626.   }
  627.   chomp $line;
  628.   $line =~ /^\+OK/ or $me->Message("Bad return from RETR: $line") and return;
  629.   $line =~ /^\+OK (\d+) / and my $buflen = $1;
  630.  
  631.   while (1) {
  632.     $line = $me->_sockread();
  633.     unless (defined $line) {
  634.     $me->Message("Socket read failed for RETR");
  635.     return;
  636.     }
  637.     last if $line =~ /^\.\s*$/;
  638.     # convert any '..' at the start of a line to '.'
  639.     $line =~ s/^\.\././;
  640.     $mandb .= $line;
  641.   }
  642.  
  643.   return wantarray ? split(/\r?\n/, $mandb) : $mandb;
  644.  
  645. } # end HeadAndBody
  646.  
  647. sub message_string { HeadAndBody(@_); }
  648.  
  649. #******************************************************************************
  650. #* get the head and body of a message and write it to a file handle.
  651. #* Sends the raw data: does no CR/NL stripping or mapping.
  652. #******************************************************************************
  653. sub HeadAndBodyToFile
  654. {
  655.   my $me = shift;
  656.   my $fh = shift;
  657.   my $num = shift;
  658.   my $body = '';
  659.  
  660.   $me->_checkstate('TRANSACTION', 'RETR') or return;
  661.   $me->_sockprint( "RETR $num", $me->EOL );
  662.   my $line = $me->_sockread();
  663.   unless (defined $line) {
  664.       $me->Message("Socket read failed for RETR");
  665.       return 0;
  666.   }
  667.   chomp $line;
  668.   $line =~ /^\+OK/ or $me->Message("Bad return from RETR: $line") and return 0;
  669.   $line =~ /^\+OK (\d+) / and my $buflen = $1;
  670.  
  671.   while (1) {
  672.     $line = $me->_sockread();
  673.     unless (defined $line) {
  674.     $me->Message("Socket read failed for RETR");
  675.     return 0;
  676.     }
  677.     last if $line =~ /^\.\s*$/;
  678.     # convert any '..' at the start of a line to '.'
  679.     $line =~ s/^\.\././;
  680.     print $fh $line;
  681.   }
  682.   return 1;
  683. } # end BodyToFile
  684.  
  685.  
  686.  
  687. #******************************************************************************
  688. #* get the body of a message
  689. #******************************************************************************
  690. sub Body
  691. {
  692.   my $me = shift;
  693.   my $num = shift;
  694.   my $body = '';
  695.  
  696.   $me->_checkstate('TRANSACTION', 'RETR') or return;
  697.   $me->_sockprint( "RETR $num", $me->EOL );
  698.   my $line = $me->_sockread();
  699.   unless (defined $line) {
  700.       $me->Message("Socket read failed for RETR");
  701.       return;
  702.   }
  703.   chomp $line;
  704.   $line =~ /^\+OK/ or $me->Message("Bad return from RETR: $line") and return;
  705.   $line =~ /^\+OK (\d+) / and my $buflen = $1;
  706.  
  707.   # skip the header
  708.   do {
  709.     $line = $me->_sockread();
  710.     unless (defined $line) {
  711.     $me->Message("Socket read failed for RETR");
  712.     return;
  713.     }
  714.   } until $line =~ /^\s*$/;
  715.  
  716.   while (1) {
  717.     $line = $me->_sockread();
  718.     unless (defined $line) {
  719.     $me->Message("Socket read failed for RETR");
  720.     return;
  721.     }
  722.     last if $line =~ /^\.\s*$/;
  723.     # convert any '..' at the start of a line to '.'
  724.     $line =~ s/^\.\././;
  725.     $body .= $line;
  726.   }
  727.  
  728.   return wantarray ? split(/\r?\n/, $body) : $body;
  729.  
  730. } # end Body
  731.  
  732.  
  733. #******************************************************************************
  734. #* get the body of a message and write it to a file handle.  Sends the raw data:
  735. #* does no CR/NL stripping or mapping.
  736. #******************************************************************************
  737. sub BodyToFile
  738. {
  739.   my $me = shift;
  740.   my $fh = shift;
  741.   my $num = shift;
  742.   my $body = '';
  743.  
  744.   $me->_checkstate('TRANSACTION', 'RETR') or return;
  745.   $me->_sockprint( "RETR $num", $me->EOL );
  746.   my $line = $me->_sockread();
  747.   unless (defined $line) {
  748.       $me->Message("Socket read failed for RETR");
  749.       return;
  750.   }
  751.   chomp $line;
  752.   $line =~ /^\+OK/ or $me->Message("Bad return from RETR: $line") and return;
  753.   $line =~ /^\+OK (\d+) / and my $buflen = $1;
  754.  
  755.   # skip the header
  756.   do {
  757.     $line = $me->_sockread();
  758.     unless (defined $line) {
  759.     $me->Message("Socket read failed for RETR");
  760.     return;
  761.     }
  762.   } until $line =~ /^\s*$/;
  763.  
  764.   while (1) {
  765.     $line = $me->_sockread();
  766.     unless (defined $line) {
  767.     $me->Message("Socket read failed for RETR");
  768.     return;
  769.     }
  770.     chomp $line;
  771.     last if $line =~ /^\.\s*$/;
  772.     # convert any '..' at the start of a line to '.'
  773.     $line =~ s/^\.\././;
  774.     print $fh $line, "\n";
  775.   }
  776. } # end BodyToFile
  777.  
  778.  
  779.  
  780. #******************************************************************************
  781. #* handle a STAT command - returns the number of messages in the box
  782. #******************************************************************************
  783. sub POPStat
  784. {
  785.   my $me = shift;
  786.  
  787.   $me->_checkstate('TRANSACTION', 'STAT') or return -1;
  788.   $me->_sockprint( "STAT", $me->EOL );
  789.   my $line = $me->_sockread();
  790.   unless (defined $line) {
  791.       $me->Message("Socket read failed for STAT");
  792.       return -1;
  793.   }
  794.   $line =~ /^\+OK/ or $me->Message("STAT failed: $line") and return -1;
  795.   $line =~ /^\+OK (\d+) (\d+)/ and $me->Count($1), $me->Size($2);
  796.  
  797.   return $me->Count();
  798. }
  799.  
  800.  
  801. #******************************************************************************
  802. #* issue the LIST command
  803. #******************************************************************************
  804. sub List {
  805.   my $me = shift;
  806.   my $num = shift || '';
  807.   my $CMD = shift || 'LIST';
  808.   $CMD=~ tr/a-z/A-Z/;
  809.  
  810.   $me->Alive() or return;
  811.  
  812.   my @retarray = ();
  813.   my $ret = '';
  814.  
  815.   $me->_checkstate('TRANSACTION', $CMD) or return;
  816.   $me->_sockprint($CMD, $num ? " $num" : '', $me->EOL());
  817.  
  818.   my $line = $me->_sockread();
  819.   unless (defined $line) {
  820.       $me->Message("Socket read failed for LIST");
  821.       return;
  822.   }
  823.   $line =~ /^\+OK/ or $me->Message("$line") and return;
  824.   if ($num) {
  825.     $line =~ s/^\+OK\s*//;
  826.     return $line;
  827.   }
  828.   while( defined( $line = $me->_sockread() ) ) {
  829.     $line =~ /^\.\s*$/ and last;
  830.     $ret .= $line;
  831.     chomp $line;
  832.     push(@retarray, $line);
  833.   }
  834.   if ($ret) {
  835.     return wantarray ? @retarray : $ret;
  836.   }
  837. }
  838.  
  839. #******************************************************************************
  840. #* issue the LIST command, but return results in an indexed array.
  841. #******************************************************************************
  842. sub ListArray {
  843.   my $me = shift;
  844.   my $num = shift || '';
  845.   my $CMD = shift || 'LIST';
  846.   $CMD=~ tr/a-z/A-Z/;
  847.  
  848.   $me->Alive() or return;
  849.  
  850.   my @retarray = ();
  851.   my $ret = '';
  852.  
  853.   $me->_checkstate('TRANSACTION', $CMD) or return;
  854.   $me->_sockprint($CMD, $num ? " $num" : '', $me->EOL());
  855.   my $line = $me->_sockread();
  856.   unless (defined $line) {
  857.       $me->Message("Socket read failed for LIST");
  858.       return;
  859.   }
  860.   $line =~ /^\+OK/ or $me->Message("$line") and return;
  861.   if ($num) {
  862.     $line =~ s/^\+OK\s*//;
  863.     return $line;
  864.   }
  865.   while( defined( $line = $me->_sockread() ) ) {
  866.     $line =~ /^\.\s*$/ and last;
  867.     $ret .= $line;
  868.     chomp $line;
  869.     my ($num, $uidl) = split('\s+', $line);
  870.     $retarray[$num] = $uidl;
  871.   }
  872.   if ($ret) {
  873.     return wantarray ? @retarray : $ret;
  874.   }
  875. }
  876.  
  877.  
  878. #******************************************************************************
  879. #* retrieve the given message number - uses HeadAndBody
  880. #******************************************************************************
  881. sub Retrieve {
  882.   return HeadAndBody( @_ );
  883. }
  884.  
  885. #******************************************************************************
  886. #* retrieve the given message number to the given file handle- uses
  887. #* HeadAndBodyToFile
  888. #******************************************************************************
  889. sub RetrieveToFile {
  890.   return HeadAndBodyToFile( @_ );
  891. }
  892.  
  893.  
  894. #******************************************************************************
  895. #* implement the LAST command - see the rfc (1081) OBSOLETED by RFC
  896. #******************************************************************************
  897. sub Last
  898. {
  899.   my $me = shift;
  900.  
  901.   $me->_checkstate('TRANSACTION', 'LAST') or return;
  902.   $me->_sockprint( "LAST", $me->EOL );
  903.   my $line = $me->_sockread();
  904.   unless (defined $line) {
  905.       $me->Message("Socket read failed for LAST");
  906.       return 0;
  907.   }
  908.  
  909.   $line =~ /\+OK (\d+)\D*$/ and return $1;
  910. }
  911.  
  912.  
  913. #******************************************************************************
  914. #* reset the deletion stat
  915. #******************************************************************************
  916. sub Reset
  917. {
  918.   my $me = shift;
  919.  
  920.   $me->_checkstate('TRANSACTION', 'RSET') or return;
  921.   $me->_sockprint( "RSET", $me->EOL );
  922.   my $line = $me->_sockread();
  923.   unless (defined $line) {
  924.       $me->Message("Socket read failed for RSET");
  925.       return 0;
  926.   }
  927.   $line =~ /^\+OK/ and return 1;
  928.   return 0;
  929. }
  930.  
  931.  
  932. #******************************************************************************
  933. #* delete the given message number
  934. #******************************************************************************
  935. sub Delete {
  936.   my $me = shift;
  937.   my $num = shift || return;
  938.  
  939.   $me->_checkstate('TRANSACTION', 'DELE') or return;
  940.   $me->_sockprint( "DELE $num",  $me->EOL );
  941.   my $line = $me->_sockread();
  942.   unless (defined $line) {
  943.       $me->Message("Socket read failed for DELE");
  944.       return 0;
  945.   }
  946.   $me->Message($line);
  947.   $line =~ /^\+OK/ && return 1;
  948.   return 0;
  949. }
  950.  
  951. sub delete_message { Delete(@_); }
  952.  
  953. #******************************************************************************
  954. #* UIDL - submitted by Dion Almaer (dion@member.com)
  955. #******************************************************************************
  956. sub Uidl
  957. {
  958.   my $me = shift;
  959.   my $num = shift || '';
  960.  
  961.   $me->Alive() or return;
  962.  
  963.   my @retarray = ();
  964.   my $ret = '';
  965.  
  966.   $me->_checkstate('TRANSACTION', 'UIDL') or return;
  967.   $me->_sockprint('UIDL', $num ? " $num" : '', $me->EOL());
  968.   my $line = $me->_sockread();
  969.   unless (defined $line) {
  970.       $me->Message("Socket read failed for UIDL");
  971.       return;
  972.   }
  973.   $line =~ /^\+OK/ or $me->Message($line) and return;
  974.   if ($num) {
  975.     $line =~ s/^\+OK\s*//;
  976.     return $line;
  977.   }
  978.   while( defined( $line = $me->_sockread() ) ) {
  979.     $line =~ /^\.\s*$/ and last;
  980.     $ret .= $line;
  981.     chomp $line;
  982.     my ($num, $uidl) = split('\s+', $line);
  983.     $retarray[$num] = $uidl;
  984.   }
  985.   if ($ret) {
  986.     return wantarray ? @retarray : $ret;
  987.   }
  988. }
  989.  
  990.  
  991. #******************************************************************************
  992. #* CAPA - query server capabilities, see RFC 2449
  993. #******************************************************************************
  994. sub Capa {
  995.  
  996.   my $me = shift;
  997.  
  998.   # no state check here, all are allowed
  999.  
  1000.   $me->Alive() or return;
  1001.  
  1002.   my @retarray = ();
  1003.   my $ret = '';
  1004.  
  1005.   $me->_sockprint('CAPA', $me->EOL());
  1006.  
  1007.   my $line = $me->_sockread();
  1008.   $line =~ /^\+OK/ or $me->Message($line) and return;
  1009.  
  1010.   while(defined($line = $me->_sockread())) {
  1011.     $line =~ /^\.\s*$/ and last;
  1012.     $ret .= $line;
  1013.     chomp $line;
  1014.     push(@retarray, $line);
  1015.   }
  1016.  
  1017.   if ($ret) {
  1018.     return wantarray ? @retarray : $ret;
  1019.   }
  1020. }
  1021.  
  1022. #******************************************************************************
  1023. #* XTND - submitted by Chris Moates (six@mox.net)
  1024. #******************************************************************************
  1025. sub Xtnd {
  1026.   my $me = shift;
  1027.   my $xtndarg = shift || '';
  1028.  
  1029.   if ($xtndarg eq '') { 
  1030.     $me->Message("XTND requires a string argument");
  1031.     return;
  1032.   }
  1033.  
  1034.   my $s = $me->Socket();
  1035.   $me->_checkstate('TRANSACTION', 'XTND') or return;
  1036.   $me->Alive() or return;
  1037.  
  1038.   $me->_sockprint( "XTND $xtndarg", $me->EOL );
  1039.   my $line = $me->_sockread();
  1040.   $line =~ /^\+OK/ or $me->Message($line) and return;
  1041.   $line =~ s/^\+OK\s*//;
  1042.   return $line;
  1043. }
  1044.  
  1045.  
  1046. #******************************************************************************
  1047. #* Mail::IMAPClient compatibility functions (wsnyder@wsnyder.org)
  1048. #******************************************************************************
  1049.  
  1050. # Empty stubs
  1051. sub Peek {}
  1052. sub Uid {}
  1053.  
  1054. # Pop doesn't have concept of different folders
  1055. sub folders { return ('INBOX'); }
  1056. sub Folder { return ('INBOX'); }
  1057. sub select {}
  1058.  
  1059. # Message accessing
  1060. sub unseen {
  1061.     my $me = shift;
  1062.     my $count = $me->Count;
  1063.     return () if !$count;
  1064.     return ( 1..$count);
  1065. }
  1066.  
  1067. #*****************************************************************************
  1068. #* Check the state before issuing a command
  1069. #*****************************************************************************
  1070. sub _checkstate
  1071. {
  1072.   my ($me, $state, $cmd) = @_;
  1073.   my $currstate = $me->State();
  1074.   if ($currstate ne $state) {
  1075.     $me->Message("POP3 command $cmd may be given only in the '$state' state " .
  1076.                  "(current state is '$currstate').");
  1077.     return 0;
  1078.   } else {
  1079.     return 1;
  1080.   }
  1081. }
  1082.  
  1083.  
  1084. #*****************************************************************************
  1085. #* funnel all read/write through here to allow easier debugging
  1086. #* (mitra@earth.path.net)
  1087. #*****************************************************************************
  1088. sub _sockprint
  1089. {
  1090.   my $me = shift;
  1091.   my $s = $me->Socket();
  1092.   $me->Debug and Carp::carp "POP3 -> ", @_;
  1093.   my $outline = "@_";
  1094.   chomp $outline;
  1095.   push(@{$me->{tranlog}}, $outline);
  1096.   print $s @_;
  1097. }
  1098.  
  1099. sub _sockread
  1100. {
  1101.   my $me = shift;
  1102.   my $line = $me->Socket()->getline();
  1103.   unless (defined $line) {
  1104.       return;
  1105.   }
  1106.  
  1107.   # Macs seem to leave CR's or LF's sitting on the socket.  This
  1108.   # removes them.
  1109.   $me->{STRIPCR} && ($line =~ s/^[\r]+//);
  1110.  
  1111.   $me->Debug and Carp::carp "POP3 <- ", $line;
  1112.   $line =~ /^[\\+\\-](OK|ERR)/i && do {
  1113.     my $l = $line;
  1114.     chomp $l;
  1115.     push(@{$me->{tranlog}}, $l);
  1116.   };
  1117.   return $line;
  1118. }
  1119.  
  1120.  
  1121. # end package Mail::POP3Client
  1122.  
  1123. # Autoload methods go after =cut, and are processed by the autosplit program.
  1124.  
  1125. 1;
  1126. __END__
  1127.  
  1128.  
  1129.  
  1130. ################################################################################
  1131. # POD Documentation (perldoc Mail::POP3Client or pod2html this_file)
  1132. ################################################################################
  1133.  
  1134. =head1 NAME
  1135.  
  1136. Mail::POP3Client - Perl 5 module to talk to a POP3 (RFC1939) server
  1137.  
  1138. =head1 SYNOPSIS
  1139.  
  1140.   use Mail::POP3Client;
  1141.   $pop = new Mail::POP3Client( USER     => "me",
  1142.                    PASSWORD => "mypassword",
  1143.                    HOST     => "pop3.do.main" );
  1144.   for( $i = 1; $i <= $pop->Count(); $i++ ) {
  1145.     foreach( $pop->Head( $i ) ) {
  1146.       /^(From|Subject):\s+/i && print $_, "\n";
  1147.     }
  1148.   }
  1149.   $pop->Close();
  1150.  
  1151.   # OR with SSL
  1152.   $pop = new Mail::POP3Client( USER     => "me",
  1153.                    PASSWORD => "mypassword",
  1154.                    HOST     => "pop3.do.main",
  1155.                    USESSL   => true,
  1156.                  );
  1157.  
  1158.   # OR
  1159.   $pop2 = new Mail::POP3Client( HOST  => "pop3.otherdo.main" );
  1160.   $pop2->User( "somebody" );
  1161.   $pop2->Pass( "doublesecret" );
  1162.   $pop2->Connect() >= 0 || die $pop2->Message();
  1163.   $pop2->Close();
  1164.  
  1165.   # OR to use your own SSL socket...
  1166.   my $socket = IO::Socket::SSL->new( PeerAddr => 'pop.securedo.main',
  1167.                                      PeerPort => 993,
  1168.                                      Proto    => 'tcp') || die "No socket!";
  1169.   my $pop = Mail::POP3Client->new();
  1170.   $pop->User('somebody');
  1171.   $pop->Pass('doublesecret');
  1172.   $pop->Socket($socket);
  1173.   $pop->Connect();
  1174.  
  1175. =head1 DESCRIPTION
  1176.  
  1177. This module implements an Object-Oriented interface to a POP3 server.
  1178. It implements RFC1939 (http://www.faqs.org/rfcs/rfc1939.html)
  1179.  
  1180. =head1 EXAMPLES
  1181.  
  1182. Here is a simple example to list out the From: and Subject: headers in
  1183. your remote mailbox:
  1184.  
  1185.   #!/usr/local/bin/perl
  1186.  
  1187.   use Mail::POP3Client;
  1188.  
  1189.   $pop = new Mail::POP3Client( USER     => "me",
  1190.                    PASSWORD => "mypassword",
  1191.                    HOST     => "pop3.do.main" );
  1192.   for ($i = 1; $i <= $pop->Count(); $i++) {
  1193.     foreach ( $pop->Head( $i ) ) {
  1194.       /^(From|Subject):\s+/i and print $_, "\n";
  1195.     }
  1196.     print "\n";
  1197.   }
  1198.  
  1199. =head1 CONSTRUCTORS
  1200.  
  1201. Old style (deprecated):
  1202.    new Mail::POP3Client( USER, PASSWORD [, HOST, PORT, DEBUG, AUTH_MODE] );
  1203.  
  1204. New style (shown with defaults):
  1205.    new Mail::POP3Client( USER      => "",
  1206.                          PASSWORD  => "",
  1207.                          HOST      => "pop3",
  1208.                          PORT      => 110,
  1209.                          AUTH_MODE => 'BEST',
  1210.                          DEBUG     => 0,
  1211.                          TIMEOUT   => 60,
  1212.                          LOCALADDR => 'xxx.xxx.xxx.xxx[:xx]',
  1213.                          SOCKET => undef,
  1214.                          USESSL => 0,
  1215.                        );
  1216.  
  1217. =over 4
  1218.  
  1219. =item *
  1220. USER is the userID of the account on the POP server
  1221.  
  1222. =item *
  1223. PASSWORD is the cleartext password for the userID
  1224.  
  1225. =item *
  1226. HOST is the POP server name or IP address (default = 'pop3')
  1227.  
  1228. =item *
  1229. PORT is the POP server port (default = 110)
  1230.  
  1231. =item *
  1232. DEBUG - any non-null, non-zero value turns on debugging (default = 0)
  1233.  
  1234. =item *
  1235. AUTH_MODE - pass 'APOP' to force APOP (MD5) authorization. (default is 'BEST')
  1236.  
  1237. =item *
  1238. TIMEOUT - set a timeout value for socket operations (default = 60)
  1239.  
  1240. =item *
  1241. LOCALADDR - allow selecting a local inet address to use
  1242.  
  1243. =back
  1244.  
  1245. =head1 METHODS
  1246.  
  1247. These commands are intended to make writing a POP3 client easier.
  1248. They do not necessarily map directly to POP3 commands defined in
  1249. RFC1081 or RFC1939, although all commands should be supported.  Some
  1250. commands return multiple lines as an array in an array context.
  1251.  
  1252. =over 8
  1253.  
  1254. =item I<new>( USER => 'user', PASSWORD => 'password', HOST => 'host',
  1255.               PORT => 110, DEBUG => 0, AUTH_MODE => 'BEST', TIMEOUT => 60,,
  1256.               LOCALADDR => 'xxx.xxx.xxx.xxx[:xx]', SOCKET => undef, USESSL => 0 )
  1257. )
  1258.  
  1259. Construct a new POP3 connection with this.  You should use the
  1260. hash-style constructor.  B<The old positional constructor is
  1261. deprecated and will be removed in a future release.  It is strongly
  1262. recommended that you convert your code to the new version.>
  1263.  
  1264. You should give it at least 2 arguments: USER and PASSWORD.  The
  1265. default HOST is 'pop3' which may or may not work for you.  You can
  1266. specify a different PORT (be careful here).
  1267.  
  1268. new will attempt to Connect to and Login to the POP3 server if you
  1269. supply a USER and PASSWORD.  If you do not supply them in the
  1270. constructor, you will need to call Connect yourself.
  1271.  
  1272. The valid values for AUTH_MODE are 'BEST', 'PASS', 'APOP' and 'CRAM-MD5'.
  1273. BEST says to try APOP if the server appears to support it and it can be
  1274. used to successfully log on, next try similarly with CRAM-MD5, and finally
  1275. revert to PASS. APOP and CRAM-MD5 imply that an MD5 checksum will be
  1276. used instead of sending your password in cleartext.  However,
  1277. B<if the server does not claim to support APOP or CRAM-MD5,
  1278. the cleartext method will be used. Be careful.> There are a few
  1279. servers that will send a timestamp in the banner greeting, but APOP
  1280. will not work with them (for instance if the server does not know your
  1281. password in cleartext).  If you think your authentication information
  1282. is correct, run in DEBUG mode and look for errors regarding
  1283. authorization.  If so, then you may have to use 'PASS' for that server.
  1284. The same applies to CRAM-MD5, too.
  1285.  
  1286. If you enable debugging with DEBUG => 1, socket traffic will be echoed
  1287. to STDERR.
  1288.  
  1289. Another warning, it's impossible to differentiate between a timeout
  1290. and a failure.
  1291.  
  1292. If you pass a true value for USESSL, the port will be changed to 995 if
  1293. it is not set or is 110.  Otherwise, it will use your port.  If USESSL
  1294. is true, IO::Socket::SSL will be loaded.  If it is not in your perl,
  1295. the call to connect will fail.
  1296.  
  1297. new returns a valid Mail::POP3CLient object in all cases.  To test for
  1298. a connection failure, you will need to check the number of messages:
  1299. -1 indicates a connection error.  This will likely change sometime in
  1300. the future to return undef on an error, setting $! as a side effect.
  1301. This change will not happen in any 2.x version.
  1302.  
  1303. =item I<Head>( MESSAGE_NUMBER [, PREVIEW_LINES ] )
  1304.  
  1305. Get the headers of the specified message, either as an array or as a
  1306. string, depending on context.
  1307.  
  1308. You can also specify a number of preview lines which will be returned
  1309. with the headers.  This may not be supported by all POP3 server
  1310. implementations as it is marked as optional in the RFC.  Submitted by
  1311. Dennis Moroney <dennis@hub.iwl.net>.
  1312.  
  1313. =item I<Body>( MESSAGE_NUMBER )
  1314.  
  1315. Get the body of the specified message, either as an array of lines or
  1316. as a string, depending on context.
  1317.  
  1318. =item I<BodyToFile>( FILE_HANDLE, MESSAGE_NUMBER )
  1319.  
  1320. Get the body of the specified message and write it to the given file handle.
  1321. my $fh = new IO::Handle();
  1322. $fh->fdopen( fileno( STDOUT ), "w" );
  1323. $pop->BodyToFile( $fh, 1 );
  1324.  
  1325. Does no stripping of NL or CR.
  1326.  
  1327.  
  1328. =item I<HeadAndBody>( MESSAGE_NUMBER )
  1329.  
  1330. Get the head and body of the specified message, either as an array of
  1331. lines or as a string, depending on context.
  1332.  
  1333. =over 4
  1334.  
  1335. =item Example
  1336.  
  1337. foreach ( $pop->HeadAndBody( 1 ) )
  1338.    print $_, "\n";
  1339.  
  1340. prints out the complete text of message 1.
  1341.  
  1342. =back
  1343.  
  1344. =item I<HeadAndBodyToFile>( FILE_HANDLE, MESSAGE_NUMBER )
  1345.  
  1346. Get the head and body of the specified message and write it to the given file handle.
  1347. my $fh = new IO::Handle();
  1348. $fh->fdopen( fileno( STDOUT ), "w" );
  1349. $pop->HeadAndBodyToFile( $fh, 1 );
  1350.  
  1351. Does no stripping of NL or CR.
  1352.  
  1353.  
  1354. =item I<Retrieve>( MESSAGE_NUMBER )
  1355.  
  1356. Same as HeadAndBody.
  1357.  
  1358. =item I<RetrieveToFile>( FILE_HANDLE, MESSAGE_NUMBER )
  1359.  
  1360. Same as HeadAndBodyToFile.
  1361.  
  1362. =item I<Delete>( MESSAGE_NUMBER )
  1363.  
  1364. Mark the specified message number as DELETED.  Becomes effective upon
  1365. QUIT (invoking the Close method).  Can be reset with a Reset message.
  1366.  
  1367. =item I<Connect>
  1368.  
  1369. Start the connection to the POP3 server.  You can pass in the host and
  1370. port.  Returns the number of messages in the mailbox, or -1 on a
  1371. connection error.  The constructors return the value of Connect, so
  1372. they will never return undef.  This will change in any version 3.x
  1373. release, but never in a 2.x release.
  1374.  
  1375. =item I<Close>
  1376.  
  1377. Close the connection gracefully.  POP3 says this will perform any
  1378. pending deletes on the server.
  1379.  
  1380. =item I<Alive>
  1381.  
  1382. Return true or false on whether the connection is active.
  1383.  
  1384. =item I<Socket>
  1385.  
  1386. Return the file descriptor for the socket, or set if supplied.
  1387.  
  1388. =item I<Size>
  1389.  
  1390. Set/Return the size of the remote mailbox.  Set by POPStat.
  1391.  
  1392. =item I<Count>
  1393.  
  1394. Set/Return the number of remote messages.  Set during Login.
  1395.  
  1396. =item I<Message>
  1397.  
  1398. The last status message received from the server or a message
  1399. describing any problem encountered.
  1400.  
  1401. =item I<State>
  1402.  
  1403. The internal state of the connection: DEAD, AUTHORIZATION, TRANSACTION.
  1404.  
  1405. =item I<POPStat>
  1406.  
  1407. Return the results of a POP3 STAT command.  Sets the size of the
  1408. mailbox.
  1409.  
  1410. =item I<List>([message_number])
  1411.  
  1412. Returns the size of the given message number when called with an
  1413. argument using the following format:
  1414.  
  1415.    <message_number> <size_in_bytes>
  1416.  
  1417. If message_number is omitted, List behaves the same as ListArray,
  1418. returning an indexed array of the sizes of each message in the same
  1419. format.
  1420.  
  1421. You can parse the size in bytes using split:
  1422.  ($msgnum, $size) = split('\s+', $pop -> List( n ));
  1423.  
  1424.  
  1425. =item I<ListArray>
  1426.  
  1427. Return a list of sizes of each message.  This returns an indexed
  1428. array, with each message number as an index (starting from 1) and the
  1429. value as the next entry on the line.  Beware that some servers send
  1430. additional info for each message for the list command.  That info may
  1431. be lost.
  1432.  
  1433. =item I<Uidl>( [MESSAGE_NUMBER] )
  1434.  
  1435. Return the unique ID for the given message (or all of them).  Returns
  1436. an indexed array with an entry for each valid message number.
  1437. Indexing begins at 1 to coincide with the server's indexing.
  1438.  
  1439. =item I<Capa>
  1440.  
  1441. Query server capabilities, as described in RFC 2449. Returns the
  1442. capabilities in an array. Valid in all states.
  1443.  
  1444. =item I<XTND>
  1445.  
  1446. Optional extended commands.  Transaction state only.
  1447.  
  1448. =item I<Last>
  1449.  
  1450. Return the number of the last message, retrieved from the server.
  1451.  
  1452. =item I<Reset>
  1453.  
  1454. Tell the server to unmark any message marked for deletion.
  1455.  
  1456. =item I<User>( [USER_NAME] )
  1457.  
  1458. Set/Return the current user name.
  1459.  
  1460. =item I<Pass>( [PASSWORD] )
  1461.  
  1462. Set/Return the current user name.
  1463.  
  1464. =item I<Login>
  1465.  
  1466. Attempt to login to the server connection.
  1467.  
  1468. =item I<Host>( [HOSTNAME] )
  1469.  
  1470. Set/Return the current host.
  1471.  
  1472. =item I<Port>( [PORT_NUMBER] )
  1473.  
  1474. Set/Return the current port number.
  1475.  
  1476. =back
  1477.  
  1478. =head1 IMAP COMPATIBILITY
  1479.  
  1480. Basic Mail::IMAPClient method calls are also supported: close, connect,
  1481. login, message_string, Password, and unseen.  Also, empty stubs are
  1482. provided for Folder, folders, Peek, select, and Uid.
  1483.  
  1484. =head1 REQUIREMENTS
  1485.  
  1486. This module does not have mandatory requirements for modules that are not part
  1487. of the standard Perl distribution. However, APOP needs need Digest::MD5 and
  1488. CRAM-MD5 needs Digest::HMAC_MD5 and MIME::Base64.
  1489.  
  1490. =head1 AUTHOR
  1491.  
  1492. Sean Dowd <pop3client@dowds.net>
  1493.  
  1494. =head1 CREDITS
  1495.  
  1496. Based loosely on News::NNTPClient by Rodger Anderson
  1497. <rodger@boi.hp.com>.
  1498.  
  1499. =head1 SEE ALSO
  1500.  
  1501. perl(1)
  1502.  
  1503. the Digest::MD5 manpage, the Digest::HMAC_MD5 manpage, the MIME::Base64 manpage
  1504.  
  1505. RFC 1939: Post Office Protocol - Version 3
  1506.  
  1507. RFC 2195: IMAP/POP AUTHorize Extension for Simple Challenge/Response
  1508.  
  1509. RFC 2449: POP3 Extension Mechanism
  1510.  
  1511. =cut
  1512.