diff options
author | Siep Kroonenberg <siepo@cybercomm.nl> | 2022-03-14 10:08:50 +0000 |
---|---|---|
committer | Siep Kroonenberg <siepo@cybercomm.nl> | 2022-03-14 10:08:50 +0000 |
commit | 49b9d8ffc05bf0c271287eb1390cabad28c6a47a (patch) | |
tree | e2e1779b1d4795d6b2c3bf92a4e2e4154d82124b /Master/tlpkg/tlperl/lib/Net/SMTP.pm | |
parent | f03a75ebd3b935ecde4dde32687fbe86161c30ed (diff) |
New tlperl 5.34
git-svn-id: svn://tug.org/texlive/trunk@62701 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Net/SMTP.pm')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Net/SMTP.pm | 195 |
1 files changed, 107 insertions, 88 deletions
diff --git a/Master/tlpkg/tlperl/lib/Net/SMTP.pm b/Master/tlpkg/tlperl/lib/Net/SMTP.pm index 5eaf4220b62..354ed8e38f3 100644 --- a/Master/tlpkg/tlperl/lib/Net/SMTP.pm +++ b/Master/tlpkg/tlperl/lib/Net/SMTP.pm @@ -1,7 +1,7 @@ # Net::SMTP.pm # # Copyright (C) 1995-2004 Graham Barr. All rights reserved. -# Copyright (C) 2013-2016 Steve Hay. All rights reserved. +# Copyright (C) 2013-2016, 2020 Steve Hay. All rights reserved. # This module is free software; you can redistribute it and/or modify it under # the same terms as Perl itself, i.e. under the terms of either the GNU General # Public License or the Artistic License, as specified in the F<LICENCE> file. @@ -19,7 +19,7 @@ use Net::Cmd; use Net::Config; use Socket; -our $VERSION = "3.11"; +our $VERSION = "3.13"; # Code for detecting if we can use SSL my $ssl_class = eval { @@ -663,57 +663,23 @@ explicit TLS encryption, i.e. SMTPS or SMTP+STARTTLS. The Net::SMTP class is a subclass of Net::Cmd and (depending on avaibility) of IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET. -=head1 EXAMPLES - -This example prints the mail domain name of the SMTP server known as mailhost: - - #!/usr/local/bin/perl -w - - use Net::SMTP; - - $smtp = Net::SMTP->new('mailhost'); - print $smtp->domain,"\n"; - $smtp->quit; - -This example sends a small message to the postmaster at the SMTP server -known as mailhost: - - #!/usr/local/bin/perl -w - - use Net::SMTP; - - my $smtp = Net::SMTP->new('mailhost'); - - $smtp->mail($ENV{USER}); - if ($smtp->to('postmaster')) { - $smtp->data(); - $smtp->datasend("To: postmaster\n"); - $smtp->datasend("\n"); - $smtp->datasend("A simple test message\n"); - $smtp->dataend(); - } else { - print "Error: ", $smtp->message(); - } - - $smtp->quit; - -=head1 CONSTRUCTOR +=head2 Class Methods =over 4 -=item new ( [ HOST ] [, OPTIONS ] ) +=item C<new([$host][, %options])> -This is the constructor for a new Net::SMTP object. C<HOST> is the +This is the constructor for a new Net::SMTP object. C<$host> is the name of the remote host to which an SMTP connection is required. On failure C<undef> will be returned and C<$@> will contain the reason for the failure. -C<HOST> is optional. If C<HOST> is not given then it may instead be +C<$host> is optional. If C<$host> is not given then it may instead be passed as the C<Host> option described below. If neither is given then the C<SMTP_Hosts> specified in C<Net::Config> will be used. -C<OPTIONS> are passed in a hash like fashion, using key and value pairs. +C<%options> are passed in a hash like fashion, using key and value pairs. Possible options are: B<Hello> - SMTP requires that you identify yourself. This option @@ -748,16 +714,14 @@ class. Alternatively B<Family> can be used. B<Timeout> - Maximum time, in seconds, to wait for a response from the SMTP server (default: 120) -B<ExactAddresses> - If true the all ADDRESS arguments must be as +B<ExactAddresses> - If true then all C<$address> arguments must be as defined by C<addr-spec> in RFC2822. If not given, or false, then Net::SMTP will attempt to extract the address from the value passed. B<Debug> - Enable debugging information - Example: - $smtp = Net::SMTP->new('mailhost', Hello => 'my.mail.domain', Timeout => 30, @@ -788,7 +752,7 @@ Example: =back -=head1 METHODS +=head1 Object Methods Unless otherwise stated all methods return either a I<true> or I<false> value, with I<true> meaning that the operation was a success. When a method @@ -801,60 +765,60 @@ documented here. =over 4 -=item banner () +=item C<banner()> Returns the banner message which the server replied with when the initial connection was made. -=item domain () +=item C<domain()> Returns the domain that the remote SMTP server identified itself as during connection. -=item hello ( DOMAIN ) +=item C<hello($domain)> Tell the remote server the mail domain which you are in using the EHLO command (or HELO if EHLO fails). Since this method is invoked automatically when the Net::SMTP object is constructed the user should normally not have to call it manually. -=item host () +=item C<host()> Returns the value used by the constructor, and passed to IO::Socket::INET, to connect to the host. -=item etrn ( DOMAIN ) +=item C<etrn($domain)> -Request a queue run for the DOMAIN given. +Request a queue run for the C<$domain> given. -=item starttls ( SSLARGS ) +=item C<starttls(%sslargs)> Upgrade existing plain connection to SSL. You can use SSL arguments as documented in L<IO::Socket::SSL>, but it will usually use the right arguments already. -=item auth ( USERNAME, PASSWORD ) +=item C<auth($username, $password)> -=item auth ( SASL ) +=item C<auth($sasl)> Attempt SASL authentication. Requires Authen::SASL module. The first form constructs a new Authen::SASL object using the given username and password; the second form uses the given Authen::SASL object. -=item mail ( ADDRESS [, OPTIONS] ) +=item C<mail($address[, %options])> -=item send ( ADDRESS ) +=item C<send($address)> -=item send_or_mail ( ADDRESS ) +=item C<send_or_mail($address)> -=item send_and_mail ( ADDRESS ) +=item C<send_and_mail($address)> -Send the appropriate command to the server MAIL, SEND, SOML or SAML. C<ADDRESS> +Send the appropriate command to the server MAIL, SEND, SOML or SAML. C<$address> is the address of the sender. This initiates the sending of a message. The method C<recipient> should be called for each address that the message is to be sent to. -The C<mail> method can some additional ESMTP OPTIONS which is passed +The C<mail> method can take some additional ESMTP C<%options> which is passed in hash like fashion, using key and value pairs. Possible options are: Size => <bytes> @@ -872,13 +836,13 @@ Status Notification). The submitter address in C<AUTH> option is expected to be in a format as required by RFC 2554, in an RFC2821-quoted form and xtext-encoded, or <> . -=item reset () +=item C<reset()> Reset the status of the server. This may be called after a message has been initiated, but before any data has been sent, to cancel the sending of the message. -=item recipient ( ADDRESS [, ADDRESS, [...]] [, OPTIONS ] ) +=item C<recipient($address[, $address[, ...]][, %options])> Notify the server that the current message should be sent to all of the addresses given. Each address is sent as a separate command to the server. @@ -886,7 +850,7 @@ Should the sending of any address result in a failure then the process is aborted and a I<false> value is returned. It is up to the user to call C<reset> if they so desire. -The C<recipient> method can also pass additional case-sensitive OPTIONS as an +The C<recipient> method can also pass additional case-sensitive C<%options> as an anonymous hash using key and value pairs. Possible options are: Notify => ['NEVER'] or ['SUCCESS','FAILURE','DELAY'] (see below) @@ -919,8 +883,9 @@ that a DSN not be returned to the sender under any conditions." $smtp->recipient(@recipients, { Notify => ['NEVER'], SkipBad => 1 }); # Good You may use any combination of these three values 'SUCCESS','FAILURE','DELAY' in -the anonymous array reference as defined by RFC3461 (see http://www.ietf.org/rfc/rfc3461.txt -for more information. Note: quotations in this topic from same.). +the anonymous array reference as defined by RFC3461 (see +L<https://www.ietf.org/rfc/rfc3461.txt> for more information. Note: quotations +in this topic from same.). A Notify parameter of 'SUCCESS' or 'FAILURE' "requests that a DSN be issued on successful delivery or delivery failure, respectively." @@ -943,67 +908,67 @@ sent to. The machine that generates a DSN will use this address to inform the sender, because he can't know if recipients get rewritten by mail servers. It is expected to be in a format as required by RFC3461, xtext-encoded. -=item to ( ADDRESS [, ADDRESS [...]] ) +=item C<to($address[, $address[, ...]])> -=item cc ( ADDRESS [, ADDRESS [...]] ) +=item C<cc($address[, $address[, ...]])> -=item bcc ( ADDRESS [, ADDRESS [...]] ) +=item C<bcc($address[, $address[, ...]])> Synonyms for C<recipient>. -=item data ( [ DATA ] ) +=item C<data([$data])> Initiate the sending of the data from the current message. -C<DATA> may be a reference to a list or a list and must be encoded by the +C<$data> may be a reference to a list or a list and must be encoded by the caller to octets of whatever encoding is required, e.g. by using the Encode module's C<encode()> function. -If specified the contents of C<DATA> and a termination string C<".\r\n"> is +If specified the contents of C<$data> and a termination string C<".\r\n"> is sent to the server. The result will be true if the data was accepted. -If C<DATA> is not specified then the result will indicate that the server +If C<$data> is not specified then the result will indicate that the server wishes the data to be sent. The data must then be sent using the C<datasend> and C<dataend> methods described in L<Net::Cmd>. -=item bdat ( DATA ) +=item C<bdat($data)> -=item bdatlast ( DATA ) +=item C<bdatlast($data)> -Use the alternate DATA command "BDAT" of the data chunking service extension +Use the alternate C<$data> command "BDAT" of the data chunking service extension defined in RFC1830 for efficiently sending large MIME messages. -=item expand ( ADDRESS ) +=item C<expand($address)> Request the server to expand the given address Returns an array which contains the text read from the server. -=item verify ( ADDRESS ) +=item C<verify($address)> -Verify that C<ADDRESS> is a legitimate mailing address. +Verify that C<$address> is a legitimate mailing address. Most sites usually disable this feature in their SMTP service configuration. Use "Debug => 1" option under new() to see if disabled. -=item help ( [ $subject ] ) +=item C<help([$subject])> Request help text from the server. Returns the text or undef upon failure -=item quit () +=item C<quit()> Send the QUIT command to the remote SMTP server and close the socket connection. -=item can_inet6 () +=item C<can_inet6()> Returns whether we can use IPv6. -=item can_ssl () +=item C<can_ssl()> Returns whether we can use SSL. =back -=head1 ADDRESSES +=head2 Addresses Net::SMTP attempts to DWIM with addresses that are passed. For example an application might extract The From: line from an email @@ -1019,23 +984,65 @@ accept the address surrounded by angle brackets. "funny user"@domain RIGHT, recommended <"funny user"@domain> OK +=head1 EXAMPLES + +This example prints the mail domain name of the SMTP server known as mailhost: + + #!/usr/local/bin/perl -w + + use Net::SMTP; + + $smtp = Net::SMTP->new('mailhost'); + print $smtp->domain,"\n"; + $smtp->quit; + +This example sends a small message to the postmaster at the SMTP server +known as mailhost: + + #!/usr/local/bin/perl -w + + use Net::SMTP; + + my $smtp = Net::SMTP->new('mailhost'); + + $smtp->mail($ENV{USER}); + if ($smtp->to('postmaster')) { + $smtp->data(); + $smtp->datasend("To: postmaster\n"); + $smtp->datasend("\n"); + $smtp->datasend("A simple test message\n"); + $smtp->dataend(); + } else { + print "Error: ", $smtp->message(); + } + + $smtp->quit; + +=head1 EXPORTS + +I<None>. + +=head1 KNOWN BUGS + +See L<https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>. + =head1 SEE ALSO L<Net::Cmd>, -L<IO::Socket::SSL> +L<IO::Socket::SSL>. =head1 AUTHOR -Graham Barr E<lt>F<gbarr@pobox.com>E<gt>. +Graham Barr E<lt>L<gbarr@pobox.com|mailto:gbarr@pobox.com>E<gt>. -Steve Hay E<lt>F<shay@cpan.org>E<gt> is now maintaining libnet as of version -1.22_02. +Steve Hay E<lt>L<shay@cpan.org|mailto:shay@cpan.org>E<gt> is now maintaining +libnet as of version 1.22_02. =head1 COPYRIGHT Copyright (C) 1995-2004 Graham Barr. All rights reserved. -Copyright (C) 2013-2016 Steve Hay. All rights reserved. +Copyright (C) 2013-2016, 2020 Steve Hay. All rights reserved. =head1 LICENCE @@ -1043,4 +1050,16 @@ This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself, i.e. under the terms of either the GNU General Public License or the Artistic License, as specified in the F<LICENCE> file. +=head1 VERSION + +Version 3.13 + +=head1 DATE + +23 Dec 2020 + +=head1 HISTORY + +See the F<Changes> file. + =cut |