POE::Filter::TranspareUserSContributed Perl DPOE::Filter::Transparent::SMTP(3)NAMEPOE::Filter::Transparent::SMTP - Make SMTP transparency a breeze :)
VERSION
VERSION: 0.2
SYNOPSIS
use POE::Filter::Transparent::SMTP;
my @array_of_things = (
q{.first thing(no new line)},
qq{.second thing (with new line)\n},
q{.third thing (no new line},
q{.}, # this is the message terminator, so it shouldn't be
# prepended with an extra dot
);
my $filter = POE::Filter::Transparent::SMTP->new( );
my $lines = $filter->put( \@array_of_things );
DESCRIPTION
The filter aims to make SMTP data transparent just before going onto
the wire as per RFC 821 Simple Mail Transfer Protocol Section 4.5.2.
TRANSPARENCY. See <http://www.faqs.org/rfcs/rfc821.html> for details.
Conversely the filter takes transparent data from the wire and converts
it to the original format.
The main purpose of this filter is to help POE::Component::Client::SMTP
create transparent messages when comunicating with an SMTP server.
However the filter can be used by any Perl SMTP client or server.
Internally it uses POE::Filter::Line in order to split messages into
lines. Also as stated in the RFC every line it puts on the wire is
ended by <CRLF>.
When receiving data from the wire (as it is the case for an SMTP
server), lines should be separated with <CRLF> as the RFC specifies.
However this is not always true as some SMTP clients are broken. So if
you are using the filter on the receiving end maybe you would like to
specify a regular expression that is more flexible for the line
terminator.
METHODS
All methods are conforming to POE::Filter specs. For more details have
a look at POE::Filter documentation.
new HASHREF_OF_PARAMETERS
my $filter = POE::Filter::Transparent::SMTP->new(
InputLiteral => qq{\015\012},
OutputLiteral => qq{\015\012},
);
Creates a new filter.
It accepts four optional arguments:
InputLiteral
InputLiteral is the same as InputLiteral for POE::Filter::Line
It defaults to whatever POE::Filter::Line is defaulting. Currently
POE::Filter::Line tries to auto-detect the line separator, but that
may lead to a race condition, please consult the POE::Filter::Line
documentation.
OutputLiteral
OutputLiteral is the same as OutputLiteral for POE::Filter::Line
It defaults to CRLF if not specified otherwise.
Warn
In case "get_one" receives lines starting with a leading dot and
"Warn" is enabled it issues a warning about this. By default the
warning is disabled.
EscapeSingleInputDot
In case you want to escape the single dot when reading data.
The parameter is useful for escaping single dots on a line when
reading message bodies. Don't use this for filtering entire SMTP
transaction logs as it will ruin your command '.'
Defaults to false
get_one_start ARRAYREF
$filter->get_one_start( $array_ref_of_formatted_lines );
Accepts an array reference to a list of unprocessed chunks and adds
them to the buffer in order to be processed.
get_one
my $array_ref = $filter->get_one(); my $line = $array_ref->[0];
Returns zero or one processed record from the raw data buffer. The
method is not greedy and is the preffered method you should use to get
processed records.
get ARRAY_REF
my $lines = $filter->get( $array_ref_of_formatted_lines );
for (my $i = 0; $i < scalar @{$lines}; $i++ ) {
# do something with $lines->[$i];
}
"get" is the greedy form of "get_one" and internally is implemented as
one call of "get_one_start" and a loop of "get_one".
Normally you shouldn't use this as using "get_one_start" and "get_one"
would make filter swapping easyer.
put ARRAYREF
my @array_of_things = (
q{.first thing(no new line)},
qq{.second thing (with new line)\n},
q{.third thing (no new line}, q{.},
);
my $lines = $filter->put( \@array_of_things );
print Dumper( $lines );
would return something similar as below
$VAR1 = [
'..first thing(no new line)
',
'..second thing (with new line)
',
'..third thing (no new line
',
'.
'
];
"put" takes an array ref of unprocessed records and prepares them to be
put on the wire making the records SMTP Transparent.
get_pending
Returns a list of data that is in the buffer (without clearing it) or
undef in case there is nothing in the buffer.
clone
my $new_filter = $filter->clone();
Clones the current filter keeping the same parameters, but with an
empty buffer.
SEE ALSO
POE POE::Filter POE::Filter::Line POE::Component::Client::SMTP
POE::Component::Server::SimpleSMTP
KNOWN ISSUES
By default, InputLiteral is set to the default POE::Filter::Line which
can become an issue if you are using the filter on the receiving end.
BUGS
Please report any bugs or feature requests to
"bug-poe-filter-transparent-smtp at rt.cpan.org", or through the web
interface at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Filter-Transparent-SMTP
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Filter-Transparent-
SMTP>. I will be notified, and then you'll automatically be notified
of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc POE::Filter::Transparent::SMTP
You can also look for information at:
· RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Filter-Transparent-SMTP
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Filter-Transparent-
SMTP>
· AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/POE-Filter-Transparent-SMTP
<http://annocpan.org/dist/POE-Filter-Transparent-SMTP>
· CPAN Ratings
http://cpanratings.perl.org/d/POE-Filter-Transparent-SMTP
<http://cpanratings.perl.org/d/POE-Filter-Transparent-SMTP>
· Search CPAN
http://search.cpan.org/dist/POE-Filter-Transparent-SMTP
<http://search.cpan.org/dist/POE-Filter-Transparent-SMTP>
ACKNOWLEDGMENTS
Thanks to Jay Jarvinen who pointed out that
POE::Component::Client::SMTP is not doing SMTP transparency as it
should (RFC 821, Section 4.5.2. TRANSPARENCY)
AUTHOR
George Nistorica, ultradm __at cpan __dot org
COPYRIGHT & LICENSE
Copyright 2008-2009 George Nistorica, all rights reserved. This
program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.1 2009-01-28 POE::Filter::Transparent::SMTP(3)
