.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Qpsmtpd::Transaction 3pm"
.TH Qpsmtpd::Transaction 3pm "2010-02-12" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Qpsmtpd::Transaction \- single SMTP session transaction data
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  foreach my $recip ($transaction\->recipients) {
\&    print "T", $recip\->address, "\e0";
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Qpsmtpd::Transaction maintains a single \s-1SMTP\s0 session's data, including
the envelope details and the mail header and body.
.PP
The docs below cover using the \f(CW$transaction\fR object from within plugins
rather than constructing a \f(CW\*(C`Qpsmtpd::Transaction\*(C'\fR object, because the
latter is done for you by qpsmtpd.
.SH "API"
.IX Header "API"
.SS "add_recipient($recipient)"
.IX Subsection "add_recipient($recipient)"
This adds a new recipient (as in \s-1RCPT\s0 \s-1TO\s0) to the envelope of the mail.
.PP
The \f(CW$recipient\fR is a \f(CW\*(C`Qpsmtpd::Address\*(C'\fR object. See Qpsmtpd::Address
for more details.
.SS "remove_recipient($recipient)"
.IX Subsection "remove_recipient($recipient)"
This removes a recipient (as in \s-1RCPT\s0 \s-1TO\s0) from the envelope of the mail.
.PP
The \f(CW$recipient\fR is a \f(CW\*(C`Qpsmtpd::Address\*(C'\fR object. See Qpsmtpd::Address
for more details.
.SS "recipients( )"
.IX Subsection "recipients( )"
This returns a list of the current recipients in the envelope.
.PP
Each recipient returned is a \f(CW\*(C`Qpsmtpd::Address\*(C'\fR object.
.PP
This method is also a setter. Pass in a list of recipients to change
the recipient list to an entirely new list. Note that the recipients
you pass in \fB\s-1MUST\s0\fR be \f(CW\*(C`Qpsmtpd::Address\*(C'\fR objects.
.SS "sender( [ \s-1ADDRESS\s0 ] )"
.IX Subsection "sender( [ ADDRESS ] )"
Get or set the sender (\s-1MAIL\s0 \s-1FROM\s0) address in the envelope.
.PP
The sender is a \f(CW\*(C`Qpsmtpd::Address\*(C'\fR object.
.SS "header( [ \s-1HEADER\s0 ] )"
.IX Subsection "header( [ HEADER ] )"
Get or set the header of the email.
.PP
The header is a <Mail::Header> object, which gives you access to all
the individual headers using a simple \s-1API\s0. e.g.:
.PP
.Vb 3
\&  my $headers = $transaction\->header();
\&  my $msgid = $headers\->get(\*(AqMessage\-Id\*(Aq);
\&  my $subject = $headers\->get(\*(AqSubject\*(Aq);
.Ve
.ie n .SS "notes( $key [, $value ] )"
.el .SS "notes( \f(CW$key\fP [, \f(CW$value\fP ] )"
.IX Subsection "notes( $key [, $value ] )"
Get or set a note on the transaction. This is a piece of data that you wish
to attach to the transaction and read somewhere else. For example you can
use this to pass data between plugins.
.PP
Note though that these notes will be lost when a transaction ends, for
example on a \f(CW\*(C`RSET\*(C'\fR or after \f(CW\*(C`DATA\*(C'\fR completes, so you might want to
use the notes field in the \f(CW\*(C`Qpsmtpd::Connection\*(C'\fR object instead.
.SS "body_filename ( )"
.IX Subsection "body_filename ( )"
Returns the temporary filename used to store the message contents; useful for
virus scanners so that an additional copy doesn't need to be made.
.PP
Calling \f(CW\*(C`body_filename()\*(C'\fR also forces spooling to disk. A message is not 
spooled to disk if it's size is smaller than 
\&\fI\f(CI$self\fI\->config(\*(L"size_threshold\*(R")\fR, default threshold is 0, the sample
config file sets this to 10000.
.ie n .SS "body_write( $data )"
.el .SS "body_write( \f(CW$data\fP )"
.IX Subsection "body_write( $data )"
Write data to the end of the email.
.PP
\&\f(CW$data\fR can be either a plain scalar, or a reference to a scalar.
.SS "body_size( )"
.IX Subsection "body_size( )"
\&\fBDepreceated\fR, Use \fI\fIdata_size()\fI\fR instead.
.SS "data_size( )"
.IX Subsection "data_size( )"
Get the current size of the email. Note that this is not the size of the 
message that will be queued, it is the size of what the client sent after
the \f(CW\*(C`DATA\*(C'\fR command. If you need the size that will be queued, use
.PP
.Vb 2
\& my $msg_len = length($transaction\->header\->as_string) 
\&   + $transaction\->body_length;
.Ve
.PP
The line above is of course only valid in \fIhook_queue( )\fR, as other plugins
may add headers and qpsmtpd will add it's \fIReceived:\fR header.
.SS "body_length( )"
.IX Subsection "body_length( )"
Get the current length of the body of the email. This length includes the
empty line between the headers and the body. Until the client has sent 
some data of the body of the message (i.e. headers are finished and client
sent the empty line) this will return 0.
.SS "body_resetpos( )"
.IX Subsection "body_resetpos( )"
Resets the body filehandle to the start of the file (via \f(CW\*(C`seek()\*(C'\fR).
.PP
Use this function before every time you wish to process the entire
body of the email to ensure that some other plugin has not moved the
file pointer.
.SS "body_getline( )"
.IX Subsection "body_getline( )"
Returns a single line of data from the body of the email.
.SS "body_fh( )"
.IX Subsection "body_fh( )"
Returns the file handle to the temporary file of the email. This will return
undef if the file is not opened (yet). In \fIhook_data( )\fR or later you can 
force spooling to disk by calling \fI\f(CI$transaction\fI\->body_filename\fR.
.SS "dup_body_fh( )"
.IX Subsection "dup_body_fh( )"
Returns a \fIdup()\fR'd file handle to the temporary file of the email. This can be
useful if an external module may call \fIclose()\fR on the filehandle that is passed
to it.  This should only be used for reads, as writing to a dup'd filehandle
may have unintended consequences.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mail::Header, Qpsmtpd::Address, Qpsmtpd::Connection