POE::Filter::Transparent::SMTP(3pm)

1POE::Filter::TransparenUts:e:rSMCToPn(t3r)ibuted Perl DoPcOuEm:e:nFtialttieorn::Transparent::SMTP(3)
2
3
4

NAME

6       POE::Filter::Transparent::SMTP - Make SMTP transparency a breeze :)
7

VERSION

9       VERSION: 0.2
10

SYNOPSIS

12        use POE::Filter::Transparent::SMTP;
13
14        my @array_of_things = (
15            q{.first thing(no new line)},
16            qq{.second thing (with new line)\n},
17            q{.third thing (no new line},
18            q{.}, # this is the message terminator, so it shouldn't be
19                  # prepended with an extra dot
20        );
21        my $filter = POE::Filter::Transparent::SMTP->new( );
22        my $lines = $filter->put( \@array_of_things );
23

DESCRIPTION

25       The filter aims to make SMTP data transparent just before going onto
26       the wire as per RFC 821 Simple Mail Transfer Protocol Section 4.5.2.
27       TRANSPARENCY. See <http://www.faqs.org/rfcs/rfc821.html> for details.
28
29       Conversely the filter takes transparent data from the wire and converts
30       it to the original format.
31
32       The main purpose of this filter is to help POE::Component::Client::SMTP
33       create transparent messages when comunicating with an SMTP server.
34       However the filter can be used by any Perl SMTP client or server.
35
36       Internally it uses POE::Filter::Line in order to split messages into
37       lines. Also as stated in the RFC every line it puts on the wire is
38       ended by <CRLF>.
39
40       When receiving data from the wire (as it is the case for an SMTP
41       server), lines should be separated with <CRLF> as the RFC specifies.
42       However this is not always true as some SMTP clients are broken. So if
43       you are using the filter on the receiving end maybe you would like to
44       specify a regular expression that is more flexible for the line
45       terminator.
46

METHODS

48       All methods are conforming to POE::Filter specs. For more details have
49       a look at POE::Filter documentation.
50
51   new HASHREF_OF_PARAMETERS
52        my $filter = POE::Filter::Transparent::SMTP->new(
53            InputLiteral => qq{\015\012},
54             OutputLiteral => qq{\015\012},
55        );
56
57       Creates a new filter.
58
59       It accepts four optional arguments:
60
61       InputLiteral
62           InputLiteral is the same as InputLiteral for POE::Filter::Line
63
64           It defaults to whatever POE::Filter::Line is defaulting. Currently
65           POE::Filter::Line tries to auto-detect the line separator, but that
66           may lead to a race condition, please consult the POE::Filter::Line
67           documentation.
68
69       OutputLiteral
70           OutputLiteral is the same as OutputLiteral for POE::Filter::Line
71
72           It defaults to CRLF if not specified otherwise.
73
74       Warn
75           In case "get_one" receives lines starting with a leading dot and
76           "Warn" is enabled it issues a warning about this. By default the
77           warning is disabled.
78
79       EscapeSingleInputDot
80           In case you want to escape the single dot when reading data.
81
82           The parameter is useful for escaping single dots on a line when
83           reading message bodies. Don't use this for filtering entire SMTP
84           transaction logs as it will ruin your command '.'
85
86           Defaults to false
87
88   get_one_start ARRAYREF
89        $filter->get_one_start( $array_ref_of_formatted_lines );
90
91       Accepts an array reference to a list of unprocessed chunks and adds
92       them to the buffer in order to be processed.
93
94   get_one
95        my $array_ref = $filter->get_one(); my $line = $array_ref->[0];
96
97       Returns zero or one processed record from the raw data buffer. The
98       method is not greedy and is the preffered method you should use to get
99       processed records.
100
101   get ARRAY_REF
102        my $lines = $filter->get( $array_ref_of_formatted_lines );
103        for (my $i = 0; $i < scalar @{$lines}; $i++ ) {
104            # do something with $lines->[$i];
105        }
106
107       "get" is the greedy form of "get_one" and internally is implemented as
108       one call of "get_one_start" and a loop of "get_one".
109
110       Normally you shouldn't use this as using "get_one_start" and "get_one"
111       would make filter swapping easyer.
112
113   put ARRAYREF
114        my @array_of_things = (
115            q{.first thing(no new line)},
116            qq{.second thing (with new line)\n},
117            q{.third thing (no new line}, q{.},
118        );
119        my $lines = $filter->put( \@array_of_things );
120        print Dumper( $lines );
121
122       would return something similar as below
123
124        $VAR1 = [
125                 '..first thing(no new line)
126        ',
127                 '..second thing (with new line)
128
129        ',
130                 '..third thing (no new line
131        ',
132                 '.
133        '
134               ];
135
136       "put" takes an array ref of unprocessed records and prepares them to be
137       put on the wire making the records SMTP Transparent.
138
139   get_pending
140       Returns a list of data that is in the buffer (without clearing it) or
141       undef in case there is nothing in the buffer.
142
143   clone
144        my $new_filter = $filter->clone();
145
146       Clones the current filter keeping the same parameters, but with an
147       empty buffer.
148

KNOWN ISSUES

154       By default, InputLiteral is set to the default POE::Filter::Line which
155       can become an issue if you are using the filter on the receiving end.
156

BUGS

158       Please report any bugs or feature requests to
159       "bug-poe-filter-transparent-smtp at rt.cpan.org", or through the web
160       interface at
161       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Filter-Transparent-SMTP
162       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Filter-Transparent-
163       SMTP>.  I will be notified, and then you'll automatically be notified
164       of progress on your bug as I make changes.
165

SUPPORT

167       You can find documentation for this module with the perldoc command.
168
169           perldoc POE::Filter::Transparent::SMTP
170
171       You can also look for information at:
172
173       ·   RT: CPAN's request tracker
174
175           http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Filter-Transparent-SMTP
176           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Filter-Transparent-
177           SMTP>
178
179       ·   AnnoCPAN: Annotated CPAN documentation
180
181           http://annocpan.org/dist/POE-Filter-Transparent-SMTP
182           <http://annocpan.org/dist/POE-Filter-Transparent-SMTP>
183
184       ·   CPAN Ratings
185
186           http://cpanratings.perl.org/d/POE-Filter-Transparent-SMTP
187           <http://cpanratings.perl.org/d/POE-Filter-Transparent-SMTP>
188
189       ·   Search CPAN
190
191           http://search.cpan.org/dist/POE-Filter-Transparent-SMTP
192           <http://search.cpan.org/dist/POE-Filter-Transparent-SMTP>
193

ACKNOWLEDGMENTS

195       Thanks to Jay Jarvinen who pointed out that
196       POE::Component::Client::SMTP is not doing SMTP transparency as it
197       should (RFC 821, Section 4.5.2.  TRANSPARENCY)
198

AUTHOR

200       George Nistorica, ultradm __at cpan __dot org
201

COPYRIGHT & LICENSE

203       Copyright 2008-2009 George Nistorica, all rights reserved.  This
204       program is free software; you can redistribute it and/or modify it
205       under the same terms as Perl itself.
206
207
208
209perl v5.12.0                      2009-01-28 POE::Filter::Transparent::SMTP(3)