unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

Mail::Transport::POP3(User Contributed Perl DocumentMail::Transport::POP3(3pm)



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.

METHODS
       Constructors

       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'
            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-OF-HOSTNAMES

           . interval => SECONDS

           . log => LEVEL

           . password => STRING

           . port => INTEGER

           . proxy => PATH

           . retry => NUMBER|undef

           . timeout => SECONDS

           . trace => LEVEL

           . username => STRING

           . via => CLASS|NAME

       Receiving mail

       $obj->receive([UNIQUE-MESSAGE-ID])

           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, ID's)

           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 ID's 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

       $obj->findBinary(NAME [, DIRECTORIES])

           See "Server connection" in Mail::Transport

       $obj->remoteHost

           See "Server connection" in Mail::Transport

       $obj->retry

           See "Server connection" in Mail::Transport

       $obj->url

           Represent this pop3 connection as URL.

       Error handling

       $obj->AUTOLOAD

           See "Error handling" in Mail::Reporter

       $obj->addReport(OBJECT)

           See "Error handling" in Mail::Reporter

       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])

       Mail::Transport::POP3->defaultTrace([LEVEL]|[LOGLEVEL,
       TRACELEVEL]|[LEVEL, CALLBACK])

           See "Error handling" in Mail::Reporter

       $obj->errors

           See "Error handling" in Mail::Reporter

       $obj->log([LEVEL [,STRINGS]])

       Mail::Transport::POP3->log([LEVEL [,STRINGS]])

           See "Error handling" in Mail::Reporter

       $obj->logPriority(LEVEL)

       Mail::Transport::POP3->logPriority(LEVEL)

           See "Error handling" in Mail::Reporter

       $obj->logSettings

           See "Error handling" in Mail::Reporter

       $obj->notImplemented

           See "Error handling" in Mail::Reporter

       $obj->report([LEVEL])

           See "Error handling" in Mail::Reporter

       $obj->reportAll([LEVEL])

           See "Error handling" in Mail::Reporter

       $obj->trace([LEVEL])

           See "Error handling" in Mail::Reporter

       $obj->warnings

           See "Error handling" in Mail::Reporter

       Cleanup

       $obj->DESTROY

           See "Cleanup" in Mail::Reporter

       $obj->inGlobalDestruction

           See "Cleanup" in Mail::Reporter

DIAGNOSTICS
       Error: Cannot connect to $host:$port for POP3: $!

           Unsuccesful in connecting to the remote POP3 server.

       Error: Cannot get the messages of pop3 via messages()

           It is not possible to retreive 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 distribution version 2.082, built on
       April 28, 2008. Website: http://perl.overmeer.net/mailbox/

LICENSE
       Copyrights 2001-2008 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://www.perl.com/perl/misc/Artistic.html



perl v5.10.0                      2008-04-28        Mail::Transport::POP3(3pm)