Provided by: libmail-box-pop3-perl_3.003-1_all bug

NAME

       Mail::Transport::POP3 - receive messages via POP3

INHERITANCE

        Mail::Transport::POP3
          is a Mail::Transport::Receive
          is a Mail::Transport
          is a Mail::Reporter

SYNOPSIS

        my $receiver = Mail::Transport::POP3->new(...);
        my $message = $receiver->receive($id);

DESCRIPTION

       Receive messages via the POP3 protocol from one remote server, as specified in rfc1939.
       This object hides much of the complications in the protocol and recovers broken
       connections automatically.  Although it is part of the MailBox distribution, this object
       can be used separately.

       You probably should not use this module, but Mail::Box::POP3.  This module is the
       interface to POP3, whereas Mail::Box::POP3 hides the protocol weirdness and works as any
       other mail folder.

       Extends "DESCRIPTION" in Mail::Transport::Receive.

METHODS

       Extends "METHODS" in Mail::Transport::Receive.

   Constructors
       Extends "Constructors" in Mail::Transport::Receive.

       Mail::Transport::POP3->new(%options)
           Create a new pop3 server connection.  One object can only handle one connection: for a
           single user to one single server.  If the server could not be reached, or when the
           login fails, this instantiating "new" will return "undef".

            -Option      --Defined in     --Default
             authenticate                   'AUTO'
             executable    Mail::Transport  undef
             hostname      Mail::Transport  'localhost'
             interval      Mail::Transport  30
             log           Mail::Reporter   'WARNINGS'
             password      Mail::Transport  undef
             port          Mail::Transport  110
             proxy         Mail::Transport  undef
             retry         Mail::Transport  <false>
             timeout       Mail::Transport  120
             trace         Mail::Reporter   'WARNINGS'
             use_ssl                        <false>
             username      Mail::Transport  undef
             via           Mail::Transport  'sendmail'

           authenticate => 'LOGIN'|'APOP'|'AUTO'
             Authenthication method.  The standard defines two methods, named LOGIN and APOP.
             The first sends the username and password in plain text to the server to get
             permission, the latter encrypts this data using MD5.  When AUTO is used, first APOP
             is tried, and then LOGIN.

           executable => FILENAME
           hostname => HOSTNAME|ARRAY
           interval => SECONDS
           log => LEVEL
           password => STRING
           port => INTEGER
           proxy => PATH
           retry => NUMBER|undef
           timeout => SECONDS
           trace => LEVEL
           use_ssl => BOOLEAN
           username => STRING
           via => CLASS|NAME

   Receiving mail
       Extends "Receiving mail" in Mail::Transport::Receive.

       $obj->receive( [$unique_message_id] )
           Inherited, see "Receiving mail" in Mail::Transport::Receive

   Exchanging information
       $obj->deleteFetched()
           Mark all messages that have been fetched with message() for deletion.  See fetched().

       $obj->deleted(BOOLEAN, @ids)
           Either mark the specified message(s) to be deleted on the remote server or unmark them
           for deletion (if the first parameter is false).  Deletion of messages will take place
           only when the connection is specifically disconnected or the last reference to the
           object goes out of scope.

       $obj->disconnect()
           Break contact with the server, if that (still) exists.  Returns true if successful.
           Please note that even if the disconnect was not successful, all knowledge of messages
           etc. will be removed from the object: the object basically has reverted to the state
           in which it was before anything was done with the mail box.

       $obj->fetched()
           Returns a reference to a list of ID's that have been fetched using message().  This
           can be used to update a database of messages that were fetched (but maybe not yet
           deleted) from the mailbox.

           Please note that if the POP3 server did not support the UIDL command, this method will
           always return undef because it is not possibly to reliably identify messages between
           sessions (other than looking at the contents of the messages themselves).

           See also deleteFetched().

       $obj->folderSize()
           Returns the total number of octets used by the mailbox on the remote server.

       $obj->header( $id, [$bodylines] )
           Returns a reference to an array which contains the header of the message with the
           specified $id.  "undef" is returned if something has gone wrong.

           The optional integer $bodylines specifies the number of lines from the body which
           should be added, by default none.

           example:

            my $ref_lines = $pop3->header($uidl);
            print @$ref_lines;

       $obj->id2n($id)
           Translates the unique $id of a message into a sequence number which represents the
           message as long a this connection to the POP3 server exists.  When the message has
           been deleted for some reason, "undef" is returned.

       $obj->ids()
           Returns a list (in list context) or a reference to a list (in scalar context) of all
           IDs which are known by the server on this moment.

       $obj->message($id)
           Returns a reference to an array which contains the lines of the message with the
           specified $id.  Returns "undef" if something has gone wrong.

           example:

            my $ref_lines = $pop3->message($uidl);
            print @$ref_lines;

       $obj->messageSize($id)
           Returns the size of the message which is indicated by the $id, in octets.  If the
           message has been deleted on the remote server, this will return "undef".

       $obj->messages()
           Returns (in scalar context only) the number of messages that are known to exist in the
           mailbox.

   Protocol internals
       The follow methods handle protocol internals, and should not be used by a normal user of
       this class.

       $obj->login()
           Establish a new connection to the POP3 server, using username and password.

       $obj->send($socket, $data)
           Send $data to the indicated socket and return the first line read from that socket.
           Logs an error if either writing to or reading from socket failed.

           This method does not attempt to reconnect or anything: if reading or writing the
           socket fails, something is very definitely wrong.

       $obj->sendList($socket, $command)
           Sends the indicated $command to the specified socket, and retrieves the response.  It
           returns a reference to an array with all the lines that were reveived after the first
           "+OK" line and before the end-of-message delimiter (a single dot on a line).  Returns
           "undef" whenever something has gone wrong.

       $obj->socket()
           Returns a connection to the POP3 server.  If there was no connection yet, it will be
           created transparently.  If the connection with the POP3 server was lost, it will be
           reconnected and the assures that internal state information (STAT and UIDL) is up-to-
           date in the object.

           If the contact to the server was still present, or could be established, an
           IO::Socket::INET object is returned.  Else, "undef" is returned and no further actions
           should be tried on the object.

       $obj->status($socket)
           Update the current status of folder on the remote POP3 server.

   Server connection
       Extends "Server connection" in Mail::Transport::Receive.

       $obj->findBinary( $name, [@directories] )
           Inherited, see "Server connection" in Mail::Transport

       $obj->remoteHost()
           Inherited, see "Server connection" in Mail::Transport

       $obj->retry()
           Inherited, see "Server connection" in Mail::Transport

       $obj->url()
           Represent this pop3 connection as URL.

   Error handling
       Extends "Error handling" in Mail::Transport::Receive.

       $obj->AUTOLOAD()
           Inherited, see "Error handling" in Mail::Reporter

       $obj->addReport($object)
           Inherited, see "Error handling" in Mail::Reporter

       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
       Mail::Transport::POP3->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback]
       )
           Inherited, see "Error handling" in Mail::Reporter

       $obj->errors()
           Inherited, see "Error handling" in Mail::Reporter

       $obj->log( [$level, [$strings]] )
       Mail::Transport::POP3->log( [$level, [$strings]] )
           Inherited, see "Error handling" in Mail::Reporter

       $obj->logPriority($level)
       Mail::Transport::POP3->logPriority($level)
           Inherited, see "Error handling" in Mail::Reporter

       $obj->logSettings()
           Inherited, see "Error handling" in Mail::Reporter

       $obj->notImplemented()
           Inherited, see "Error handling" in Mail::Reporter

       $obj->report( [$level] )
           Inherited, see "Error handling" in Mail::Reporter

       $obj->reportAll( [$level] )
           Inherited, see "Error handling" in Mail::Reporter

       $obj->trace( [$level] )
           Inherited, see "Error handling" in Mail::Reporter

       $obj->warnings()
           Inherited, see "Error handling" in Mail::Reporter

   Cleanup
       Extends "Cleanup" in Mail::Transport::Receive.

       $obj->DESTROY()
           Inherited, see "Cleanup" in Mail::Reporter

DIAGNOSTICS

       Error: Cannot connect to $host:$port for POP3: $!
           Unsuccessful in connecting to the remote POP3 server.

       Error: Cannot get the messages of pop3 via messages()
           It is not possible to retrieve all messages on a remote POP3 folder at once: each
           shall be taken separately.  The POP3 folder will hide this for you.

       Error: Cannot re-connect reliably to server which doesn't support UIDL.
           The connection to the remote POP3 was lost, and cannot be re-established because the
           server's protocol implementation lacks the necessary information.

       Error: Cannot read POP3 from socket: $!
           It is not possible to read the success status of the previously given POP3 command.
           Connection lost?

       Error: Cannot write POP3 to socket: $@
           It is not possible to send a protocol command to the POP3 server.  Connection lost?

       Error: Could not authenticate using '$some' method.
           The authenication method to get access to the POP3 server did not result in a
           connection.  Maybe you need a different authentication protocol, or your username with
           password are invalid.

       Error: Could not authenticate using any login method.
           No authentication method was explicitly prescribed, so both AUTH and APOP were tried.
           However, both failed.  There are other authentication methods, which are not defined
           by the main POP3 RFC rfc1939.  These protocols are not implemented yet.  Please
           contribute your implementation.

       Error: POP3 Could not do a STAT
           For some weird reason, the server does not respond to the STAT call.

       Error: POP3 requires a username and password.
           No username and/or no password specified for this POP3 folder, although these are
           obligatory parts in the protocol.

       Error: Package $package does not implement $method.
           Fatal error: the specific package (or one of its superclasses) does not implement this
           method where it should. This message means that some other related classes do
           implement this method however the class at hand does not.  Probably you should
           investigate this and probably inform the author of the package.

       Error: Server at $host:$port does not seem to be talking POP3.
           The remote server did not respond to an initial exchange of messages as is expected by
           the POP3 protocol.  The server has probably a different service on the specified port.

SEE ALSO

       This module is part of Mail-Box-POP3 distribution version 3.003, built on July 16, 2017.

       Do not forget to read Mail::Box-Overview, Mail::Box-Cookbook, and Mail::Box-Index.
       Examples are included in the Mail-Box distribution, directories 'examples' and 'scripts'.

       Browseable manuals, papers, and other released material van be found at  Website:
       http://perl.overmeer.net/mailbox/

       The central modules (in separate distributions) in the MailBox suite are: Mail::Message,
       Mail::Box, Mail::Box::IMAP4, Mail::Box::POP3, Mail::Box::Parser::C, Mail::Box::Dbx
       (unpublished), Mail::Transport, Object::Realize::Later, and User::Identity.

       Please post questions or ideas to the author markov@cpan.org.

LICENSE

       Copyrights 2001-2017 by [Mark Overmeer]. For other contributors see ChangeLog.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See http://dev.perl.org/licenses/