Mail-IMAPClient
view release on metacpan or search on metacpan
+ created _response_code_sub() to simplify _get_response()
- remove internal "Folders" cache
- Allow for RFC 6154 "IMAP LIST Extension for Special-Use Mailboxes"
[Mathias Reitinger]
+ new method: folders_hash()
+ deprecate: xlist_folders(), xlist()
version 3.33: Tue, May 14, 2013 10:12:43 AM
- more cleanup on use of $@ and $!
- cleanup get_bodystructure / get_envelope
- allow Ssl arg as an arrayref to pass args to IO::Socket::SSL
[Ramana V Mokkapati]
- no need to Massage() the folder name in uidnext()
- rt.cpan.org#84028: get_envelope() fails when subject ends w/backslash
[Andy Lyttle]
- rt.cpan.org#79476: move()/copy() with sequence causes numeric warning
[Oleg G]
- *move()/copy() no longer sort message(s) provided by caller
version 3.32: Fri, Aug 10, 2012 4:43:24 PM
- document RFC2087 quota related calls
- update comments related to _list_response_preprocess
version 3.19_01: Fri Jun 5 15:45:05 EDT 2009
- make parse_headers more robust to errors/non-header data
version 3.18: Wed Jun 3 23:07:12 EDT 2009
- enhance fetch_hash to enable caller to specify list of messages
suggestion by [Eugene Mamaev]
- better handling of untagged BYE response
version 3.18_02: Wed May 27 10:02:24 EDT 2009
- *new attribute Ssl, when true causes IO::Socket::SSL to be
used instead of IO::Socket::INET. This change allows
Reconnectretry logic to work on SSL connections too.
- have LastError cluck() if setting error to NO not connected
- handle errors from imap4rev1() in multiple places
- Reconnectretry/_imap_command enhancements/fixes
+ only run command if IsConnected
+ keep a temporary history of LastError(s)
+ sets LastError to NO not connected if ! IsConnected
+ retry =~ timeout|socket closed|* BYE| NO not connected
- _imap_command_do reduce data logged when using APPEND
- set LastError when the imap_command receives an unexpected 'BYE' answer.
rt.cpan.org#44762 [Phil Lobbes]
- handle SIGPIPE cleanly.
rt.cpan.org#43414 [Phil Lobbes]
- improve handling of quotes in folder names
rt.cpan.org#43445 [Phil Lobbes]
- do not use $socket->eof(), because IO::Socket::SSL does not support it.
rt.cpan.org#43415 [Phil Lobbes]
- remove excessive reconfiguration of fastio in _read_line()
rt.cpan.org#43413 [Phil Lobbes]
Improvements:
- remove experied docs about automatically created calls, which
do not exist since 3.00
Makefile.PL view on Meta::CPAN
use 5.008_001;
my @missing;
my %optional = (
"Authen::NTLM" => { for => "Authmechanism 'NTLM'" },
"Authen::SASL" => { for => "Authmechanism 'DIGEST-MD5'" },
"Compress::Zlib" => { for => "COMPRESS DEFLATE support" },
"Digest::HMAC_MD5" => { for => "Authmechanism 'CRAM-MD5'" },
"Digest::MD5" => { for => "Authmechanism 'DIGEST-MD5'" },
"IO::Socket::IP" => { for => "IPv6 support" },
"IO::Socket::SSL" => { for => "SSL enabled connections (Ssl => 1)" },
"Test::Pod" => { for => "Pod tests", ver => "1.00" },
);
foreach my $mod ( sort keys %optional ) {
my $for = $optional{$mod}->{"for"} || "";
my $ver = $optional{$mod}->{"ver"} || "";
eval "use $mod $ver ();";
push @missing, $mod . ( $for ? " for $for" : "" ) if $@;
}
Required:
List::Util
MIME::Base64
Parse::RecDescent
Optional:
Authen::NTLM
Authen::SASL
Compress::Zlib
Digest::HMAC_MD5
Digest::MD5
IO::Socket::SSL
- RFC 3501 (IMAP4REV1) compatible IMAP server
https://tools.ietf.org/html/rfc3501
- Mail::IMAPClient (this package)
INSTALLATION
============
1. Download Mail::IMAPClient module
https://metacpan.org/release/Mail-IMAPClient
2. Read this README
examples/imap_to_mbox.pl view on Meta::CPAN
# elimination (sobek)
# TODO:
# -----
# lsub instead of list option
use warnings;
use strict;
use Mail::IMAPClient; # a nice set of perl libs for imap
use IO::Socket::SSL; # for SSL support
use vars qw($opt_h $opt_u $opt_p $opt_P $opt_s $opt_i $opt_f $opt_m $opt_b
$opt_c $opt_r $opt_w $opt_W $opt_S $opt_D $opt_U $opt_d $opt_I
$opt_n);
use Getopt::Std; # for the command-line overrides. good for user
use File::Path; # create full file paths. (yummy!)
use File::Basename; # find a nice basename for a folder.
use Date::Manip; # to create From header date
$| = 1;
examples/imap_to_mbox.pl view on Meta::CPAN
connect_imap();
find_folders();
sub connect_imap()
{
# Open an SSL session to the IMAP server
# Handles the SSL setup, and gives us back a socket
my $ssl;
if ($opt_S) {
$ssl=IO::Socket::SSL->new(
PeerHost => "$SERVER:imaps"
# , SSL_version => 'SSLv2' # for older versions of openssl
);
defined $ssl
or die "Error connecting to $SERVER:imaps - $@";
$ssl->autoflush(1);
}
lib/Mail/IMAPClient.pm view on Meta::CPAN
FROM HEADER KEYWORD LARGER NEW NOT OLD ON OR RECENT
SEEN SENTBEFORE SENTON SENTSINCE SINCE SMALLER SUBJECT
TEXT TO UID UNANSWERED UNDELETED UNDRAFT UNFLAGGED
UNKEYWORD UNSEEN);
# modules require(d) during runtime when applicable
my %Load_Module = (
"Compress-Zlib" => "Compress::Zlib",
"INET" => "IO::Socket::INET",
"IP" => "IO::Socket::IP",
"SSL" => "IO::Socket::SSL",
"UNIX" => "IO::Socket::UNIX",
"BodyStructure" => "Mail::IMAPClient::BodyStructure",
"Envelope" => "Mail::IMAPClient::BodyStructure::Envelope",
"Thread" => "Mail::IMAPClient::Thread",
);
sub _load_module {
my $self = shift;
my $modkey = shift;
my $module = $Load_Module{$modkey} || $modkey;
lib/Mail/IMAPClient.pm view on Meta::CPAN
$emsg .= " ($temperrs)";
}
else {
undef $emsg;
next; # try again
}
}
}
}
# EOF: note IO::Socket::SSL does not support eof()
if ( defined $ret and $ret == 0 ) {
$emsg = "socket closed while reading data from server";
$self->State(Unconnected);
}
elsif ( defined $ret and $ret > 0 ) {
$litreadb += $ret;
# conserve memory when using literal_callback GLOB
if ( $literal_cbtype eq "GLOB" ) {
print $literal_callback $litstring;
lib/Mail/IMAPClient.pm view on Meta::CPAN
my $self = shift;
my $rm = $self->Readmoremethod;
$rm ? $rm->( $self, @_ ) : $self->__read_more(@_);
}
sub __read_more {
my $self = shift;
my $opt = ref( $_[0] ) eq "HASH" ? shift : {};
my ( $socket, $timeout ) = @_;
# IO::Socket::SSL buffers some data internally, so there might be some
# data available from the previous sysread of which the file-handle
# (used by select()) doesn't know of.
return 1 if $socket->isa("IO::Socket::SSL") && $socket->pending;
my $rvec = '';
vec( $rvec, fileno($socket), 1 ) = 1;
my $rc = CORE::select( $rvec, undef, $rvec, $timeout );
# fast track success
return $rc if $rc > 0;
# by default set an error on timeout
lib/Mail/IMAPClient.pod view on Meta::CPAN
=head2 starttls
Example:
$imap->starttls() or die "starttls failed: $@\n";
The B<starttls> method accepts no arguments. This method is used to
upgrade an exiting connection which is not authenticated to a TLS/SSL
connection by using the IMAP STARTTLS command followed by using the
B<start_SSL> class method from L<IO::Socket::SSL> to do the necessary
TLS negotiation. The negotiation is done in a blocking fashion with a
default B<Timeout> of 30 seconds. The arguments used in the call to
B<start_SSL> can be controlled by setting the Mail::IMAPClient
L</Starttls> attribute to an ARRAY reference containing the desired
arguments.
Version note: method added in Mail::IMAPClient 3.22
=head2 status
lib/Mail/IMAPClient.pod view on Meta::CPAN
Example:
$socket = $imap->RawSocket;
# or:
$imap->RawSocket($socketh);
The I<RawSocket> method can be used to obtain the socket handle of the
current connection (say, to do I/O on the connection that is not
otherwise supported by Mail::IMAPClient) or to replace the current
socket with a new handle (for instance an SSL handle, see
L<IO::Socket::SSL>, but be sure to see the L</Socket> method as well).
If you supply a socket handle yourself, either by doing something like:
$imap=Mail::IMAPClient->new(RawSocket => $sock, User => ... );
or by doing something like:
$imap = Mail::IMAPClient->new(User => $user,
Password => $pass, Server => $host);
# blah blah blah
lib/Mail/IMAPClient.pod view on Meta::CPAN
Example:
$Socket = $imap->Socket();
# or:
$imap->Socket($socket_fh);
The I<Socket> method can be used to obtain the socket handle of the
current connection. This may be necessary to do I/O on the connection
that is not otherwise supported by Mail::IMAPClient) or to replace the
current socket with a new handle (for instance an SSL handle, see
IO::Socket::SSL).
If you supply a socket handle yourself, either by doing something like:
$imap = Mail::IMAPClient->new( Socket => $sock, User => ... );
or by doing something like:
$imap = Mail::IMAPClient->new(
User => $user, Password => $pass, Server => $host
);
lib/Mail/IMAPClient.pod view on Meta::CPAN
call L</login> if the conditions apply (see L</connect> for details);
=item *
leave the I<Mail::IMAPClient> object in a suitable state.
=back
For these reasons, the following example will work "out of the box":
use IO::Socket::SSL;
my $imap = Mail::IMAPClient->new
( User => 'your-username',
Password => 'your-password',
Socket => IO::Socket::SSL->new
( Proto => 'tcp',
PeerAddr => 'some.imap.server',
PeerPort => 993, # IMAP over SSL standard port
),
);
If you need more control over the socket, e.g. you have to implement a
fancier authentication method, see L</RawSocket>.
=head2 Starttls
If an IMAP connection must start TLS/SSL after connecting to a server
then set this attribute. If the value is set to an arrayref then they
will be used as arguments to IO::Socket::SSL->start_SSL. By default
this connection is set to blocking while establishing the connection
with a timeout of 30 seconds. The socket will be reset to the
original blocking/non-blocking value after a successful TLS
negotiation has occurred. The arguments used in the call to start_SSL
can be controlled by setting this attribute to an ARRAY reference
containing the desired arguments.
Version note: attribute added in Mail::IMAPClient 3.22
=head2 Socketargs
lib/Mail/IMAPClient.pod view on Meta::CPAN
can be controlled by setting this attribute to an ARRAY reference
containing the desired arguments.
For example, to always pass MultiHomed => 1 to IO::Socket::...->new
the following can be used:
$imap = Mail::IMAPClient->new(
..., Socketargs => [ MultiHomed => 1 ], ...
);
See also L</Ssl> for specific control of the args to IO::Socket::SSL.
Version note: attribute added in Mail::IMAPClient 3.34
=head2 Ssl
If an IMAP connection requires SSL you can set the Ssl attribute to
'1' and Mail::IMAPClient will automatically use L<IO::Socket::SSL>
instead of IO::Socket::(INET|IP) to connect to the server. This
attribute is used in the L</connect> method. The arguments used in
the call to IO::Socket::SSL->new can be controlled by setting this
attribute to an ARRAY reference containing the desired arguments.
See also L</connect> for details on connection initiation and
L</Socket> and L</Rawsocket> if you need to take more control of
connection management.
Version note: attribute added in Mail::IMAPClient 3.18
=head2 Supportedflags
lib/Mail/IMAPClient.pod view on Meta::CPAN
documentation for details.
=item Socket and RawSocket
The L</Socket> and L</RawSocket> methods provide access to the socket
connection. The socket is typically automatically created by the
L</connect> method, but if you are implementing an advanced
authentication technique you may choose to set up your own socket
connection and then set this parameter manually, bypassing the
B<connect> method completely. This is also useful if you want to use
IO::Socket::(INET|IP) alternatives like IO::Socket::SSL and need full
control.
L</RawSocket> simply gets/sets the socket without attempting any
interaction on it. In this case, you have to be sure to handle all
the preliminary operations and manually set the Mail::IMAPClient
object in sync with its actual status with respect to this socket (see
below for additional parameters regarding this, especially the
L</State> parameter).
Unlike L</RawSocket>, L</Socket> attempts to carry on preliminary
( run in 0.548 second using v1.01-cache-2.11-cpan-fd5d4e115d8 )