/usr/share/perl5/Mail/Transport/POP3.pod is in libmail-box-perl 2.099-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 | =head1 NAME
Mail::Transport::POP3 - receive messages via POP3
=head1 INHERITANCE
Mail::Transport::POP3
is a Mail::Transport::Receive
is a Mail::Transport
is a Mail::Reporter
=head1 SYNOPSIS
my $receiver = Mail::Transport::POP3->new(...);
my $message = $receiver->receive($id);
=head1 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 B<not use this> module, but L<Mail::Box::POP3|Mail::Box::POP3>. This
module is the interface to POP3, whereas L<Mail::Box::POP3|Mail::Box::POP3> hides the
protocol weirdness and works as any other mail folder.
=head1 METHODS
=head2 Constructors
=over 4
=item Mail::Transport::POP3-E<gt>B<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 C<new>
will return C<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'
=over 2
=item 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.
=item executable => FILENAME
=item hostname => HOSTNAME|ARRAY-OF-HOSTNAMES
=item interval => SECONDS
=item log => LEVEL
=item password => STRING
=item port => INTEGER
=item proxy => PATH
=item retry => NUMBER|undef
=item timeout => SECONDS
=item trace => LEVEL
=item use_ssl => BOOLEAN
=item username => STRING
=item via => CLASS|NAME
=back
=back
=head2 Receiving mail
=over 4
=item $obj-E<gt>B<receive>([UNIQUE-MESSAGE-ID])
See L<Mail::Transport::Receive/"Receiving mail">
=back
=head2 Exchanging information
=over 4
=item $obj-E<gt>B<deleteFetched>
Mark all messages that have been fetched with L<message()|Mail::Transport::POP3/"Exchanging information"> for deletion.
See L<fetched()|Mail::Transport::POP3/"Exchanging information">.
=item $obj-E<gt>B<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 B<only> when the connection is specifically
disconnected or the last reference to the object goes out of scope.
=item $obj-E<gt>B<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.
=item $obj-E<gt>B<fetched>
Returns a reference to a list of ID's that have been fetched using
L<message()|Mail::Transport::POP3/"Exchanging information">. 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 L<deleteFetched()|Mail::Transport::POP3/"Exchanging information">.
=item $obj-E<gt>B<folderSize>
Returns the total number of octets used by the mailbox on the remote server.
=item $obj-E<gt>B<header>(ID, [BODYLINES])
Returns a reference to an array which contains the header of the message
with the specified ID. C<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;
=item $obj-E<gt>B<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, C<undef>
is returned.
=item $obj-E<gt>B<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.
=item $obj-E<gt>B<message>(ID)
Returns a reference to an array which contains the lines of the
message with the specified ID. Returns C<undef> if something has gone
wrong.
example:
my $ref_lines = $pop3->message($uidl);
print @$ref_lines;
=item $obj-E<gt>B<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
C<undef>.
=item $obj-E<gt>B<messages>
Returns (in scalar context only) the number of messages that are known
to exist in the mailbox.
=back
=head2 Protocol internals
The follow methods handle protocol internals, and should not be used
by a normal user of this class.
=over 4
=item $obj-E<gt>B<login>
Establish a new connection to the POP3 server, using username and password.
=item $obj-E<gt>B<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 B<not> attempt to reconnect or anything: if reading or
writing the socket fails, something is very definitely wrong.
=item $obj-E<gt>B<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 C<+OK> line and before the end-of-message
delimiter (a single dot on a line). Returns C<undef>
whenever something has gone wrong.
=item $obj-E<gt>B<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, C<undef> is returned and
no further actions should be tried on the object.
=item $obj-E<gt>B<status>(SOCKET)
Update the current status of folder on the remote POP3 server.
=back
=head2 Server connection
=over 4
=item $obj-E<gt>B<findBinary>(NAME [, DIRECTORIES])
See L<Mail::Transport/"Server connection">
=item $obj-E<gt>B<remoteHost>
See L<Mail::Transport/"Server connection">
=item $obj-E<gt>B<retry>
See L<Mail::Transport/"Server connection">
=item $obj-E<gt>B<url>
Represent this pop3 connection as URL.
=back
=head2 Error handling
=over 4
=item $obj-E<gt>B<AUTOLOAD>
See L<Mail::Reporter/"Error handling">
=item $obj-E<gt>B<addReport>(OBJECT)
See L<Mail::Reporter/"Error handling">
=item $obj-E<gt>B<defaultTrace>([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
=item Mail::Transport::POP3-E<gt>B<defaultTrace>([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
See L<Mail::Reporter/"Error handling">
=item $obj-E<gt>B<errors>
See L<Mail::Reporter/"Error handling">
=item $obj-E<gt>B<log>([LEVEL [,STRINGS]])
=item Mail::Transport::POP3-E<gt>B<log>([LEVEL [,STRINGS]])
See L<Mail::Reporter/"Error handling">
=item $obj-E<gt>B<logPriority>(LEVEL)
=item Mail::Transport::POP3-E<gt>B<logPriority>(LEVEL)
See L<Mail::Reporter/"Error handling">
=item $obj-E<gt>B<logSettings>
See L<Mail::Reporter/"Error handling">
=item $obj-E<gt>B<notImplemented>
See L<Mail::Reporter/"Error handling">
=item $obj-E<gt>B<report>([LEVEL])
See L<Mail::Reporter/"Error handling">
=item $obj-E<gt>B<reportAll>([LEVEL])
See L<Mail::Reporter/"Error handling">
=item $obj-E<gt>B<trace>([LEVEL])
See L<Mail::Reporter/"Error handling">
=item $obj-E<gt>B<warnings>
See L<Mail::Reporter/"Error handling">
=back
=head2 Cleanup
=over 4
=item $obj-E<gt>B<DESTROY>
See L<Mail::Reporter/"Cleanup">
=item $obj-E<gt>B<inGlobalDestruction>
See L<Mail::Reporter/"Cleanup">
=back
=head1 DIAGNOSTICS
=over 4
=item Error: Cannot connect to $host:$port for POP3: $!
Unsuccesful in connecting to the remote POP3 server.
=item 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.
=item 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.
=item Error: Cannot read POP3 from socket: $!
It is not possible to read the success status of the previously given POP3
command. Connection lost?
=item Error: Cannot write POP3 to socket: $@
It is not possible to send a protocol command to the POP3 server. Connection
lost?
=item 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.
=item 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.
=item Error: POP3 Could not do a STAT
For some weird reason, the server does not respond to the STAT call.
=item 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.
=item 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.
=item 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.
=back
=head1 SEE ALSO
This module is part of Mail-Box distribution version 2.099,
built on July 07, 2011. Website: F<http://perl.overmeer.net/mailbox/>
=head1 LICENSE
Copyrights 2001-2011 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 F<http://www.perl.com/perl/misc/Artistic.html>
|