.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" 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" '' . ds C` . ds C' '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. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" 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 "Courier::Message 3pm" .TH Courier::Message 3pm "2015-11-28" "perl v5.20.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" Courier::Message \- Class implementing an interface to a mail message in the Courier MTA's message queue. .SH "VERSION" .IX Header "VERSION" 0.200 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Courier::Message; \& \& my $message = Courier::Message\->new( \& file_name => $message_file_name, \& control_file_names => \e@control_file_names, \& ); \& \& # File names: \& my $message_file_name = $message\->file_name; \& my @control_file_names = $message\->control_file_names; \& \& # Message data properties: \& my $raw_message_text = $message\->text; \& my $header_hash = $message\->header; \& my $header_field = $message\->header($field); \& my $raw_body = $message\->body; \& \& # Control properties: \& my $control_hash = $message\->control; \& my $is_authenticated = $message\->authenticated; \& my $authenticated_user = $message\->authenticated_user; \& my $is_trusted = $message\->trusted; \& my $sender = $message\->sender; \& my @recipients = $message\->recipients; \& my $remote_host = $message\->remote_host; \& my $remote_host_name = $message\->remote_host_name; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBCourier::Message\fR encapsulates a mail message that is stored in the Courier \&\s-1MTA\s0's message queue, including the belonging control file(s), and provides an easy to use, read-only interface through its message data and control properties. For light-weight calling of library functions or external commands, the message and control file names may be retrieved without causing the files to be parsed by \fBCourier::Message\fR. .SS "Constructor" .IX Subsection "Constructor" The following constructor is provided: .IP "\fBnew(%options)\fR: returns \fICourier::Message\fR" 4 .IX Item "new(%options): returns Courier::Message" Creates a new \f(CW\*(C`Courier::Message\*(C'\fR object from the given message file name and zero or more control file names. .Sp \&\f(CW%options\fR is a list of key/value pairs representing any of the following options: .RS 4 .IP "\fBfile_name\fR" 4 .IX Item "file_name" \&\fIRequired\fR. The absolute file name of the message file. .IP "\fBcontrol_file_names\fR" 4 .IX Item "control_file_names" \&\fIRequired\fR. An array-ref containing the absolute file name(s) of zero or more control files belonging to the message. .RE .RS 4 .RE .SS "Instance methods" .IX Subsection "Instance methods" \fIFile names\fR .IX Subsection "File names" .PP The following file name accessors are provided: .IP "\fBfile_name\fR: returns \fIstring\fR" 4 .IX Item "file_name: returns string" Returns the absolute file name of the message file. .IP "\fBcontrol_file_names\fR: returns \fIlist\fR of \fIstring\fR" 4 .IX Item "control_file_names: returns list of string" Returns the absolute file names of the control files belonging to the message. .PP \fIMessage data properties\fR .IX Subsection "Message data properties" .IP "\fBtext\fR: returns \fIstring\fR; throws Perl exceptions" 4 .IX Item "text: returns string; throws Perl exceptions" Reads the message text from the message file into memory once. Returns the raw message text as bytes (see bytes, and \*(L"bytes\*(R" in PerlIO). Throws a Perl exception if the message file cannot be read. .IP "\fBheader\fR: returns \fIhash-ref\fR of \fIstring\fR" 4 .IX Item "header: returns hash-ref of string" .PD 0 .IP "\fBheader($field)\fR: returns \fIlist\fR of \fIstring\fR" 4 .IX Item "header($field): returns list of string" .PD Parses the message header once by doing the following: tries to interpret the header as \fI\s-1UTF\-8\s0\fR, falling back to the 8\-bit legacy encoding \fIWindows\-1252\fR (a superset of \fI\s-1ISO\-8859\-1\s0\fR) and decoding that to \fI\s-1UTF\-8\s0\fR; parses header fields from the header; and decodes any \s-1MIME\s0 encoded words in field values. If no field name is specified, returns a hash-ref containing all header fields and array-refs of their values. If a (case \fIin\fRsensitive) field name is specified, in list context returns a list of the values of all header fields of that name, in the order they occurred in the message header, or in scalar context returns the value of the first header field of that name (or \fBundef\fR if no such header field exists). .IP "\fBbody\fR: returns \fIstring\fR" 4 .IX Item "body: returns string" Returns the raw message body as bytes (see bytes, and \*(L"bytes\*(R" in PerlIO). .PP \fIControl properties\fR .IX Subsection "Control properties" .IP "\fBcontrol\fR: returns \fIhash-ref\fR of \fIstring\fR; throws Perl exceptions" 4 .IX Item "control: returns hash-ref of string; throws Perl exceptions" .PD 0 .IP "\fBcontrol($field)\fR: returns \fIlist\fR of \fIstring\fR; throws Perl exceptions" 4 .IX Item "control($field): returns list of string; throws Perl exceptions" .PD Reads and parses all of the message's control files once. If a (case sensitive) field name (i.e. record type) is specified, returns a list of the values of all control fields of that name, in the order they occurred in the control file(s). If no field name is specified, returns a hash-ref containing all control fields and array-refs of their values. Throws a Perl exception if any of the control files cannot be read. .IP "\fBauthenticated\fR: returns \fIboolean\fR" 4 .IX Item "authenticated: returns boolean" Returns the authentication information (guaranteed to be a \fBtrue\fR value) if the message has been submitted by an authenticated user. Returns \fBfalse\fR otherwise. .Sp \&\fINote\fR: The authentication status and information is currently determined and taken from the message's first (i.e. the trustworthy) \*(L"Received\*(R" header field. This is guaranteed to work correctly, but is not very elegant, so this is subject to change. As soon as Courier supports storing the complete authentication info (including the authenticated user name) in a control field, \&\fIthat\fR will be the preferred source. This mostly just means that the \&\fIformat\fR of the authentication info will probably change in the future. .IP "\fBauthenticated_user\fR: returns \fIstring\fR" 4 .IX Item "authenticated_user: returns string" Returns the user name that was used for authentication during submission of the message. Returns \fBundef\fR if no authentication took place. .IP "\fBtrusted\fR: returns \fIboolean\fR" 4 .IX Item "trusted: returns boolean" Returns a boolean value indicating whether the message is trusted. Currently, trusted messages are defined to be messages directly submitted by an authenticated user. For details on how the authenticated status is determined, see the description of the \f(CW\*(C`authenticated\*(C'\fR property. .IP "\fBsender\fR: returns \fIstring\fR" 4 .IX Item "sender: returns string" Returns the message's envelope sender (from the \*(L"\s-1MAIL FROM\*(R" SMTP\s0 command). .IP "\fBrecipients\fR: returns \fIlist\fR of \fIstring\fR" 4 .IX Item "recipients: returns list of string" Returns all of the message's envelope recipients (from the \*(L"\s-1RCPT TO\*(R" SMTP\s0 commands). .IP "\fBremote_host\fR: returns \fIstring\fR" 4 .IX Item "remote_host: returns string" Returns the \s-1IP\s0 address of the \s-1SMTP\s0 client that submitted the message. .IP "\fBremote_host_name\fR: returns \fIstring\fR" 4 .IX Item "remote_host_name: returns string" Returns the host name (gained by Courier through a \s-1DNS\s0 reverse lookup) of the \&\s-1SMTP\s0 client that submitted the message, if available. .IP "\fBremote_host_helo\fR: returns \fIstring\fR" 4 .IX Item "remote_host_helo: returns string" Returns the \s-1HELO\s0 string that the \s-1SMTP\s0 client specified, if available. .SH "SEE ALSO" .IX Header "SEE ALSO" For \s-1AVAILABILITY, SUPPORT,\s0 and \s-1LICENSE\s0 information, see Courier::Filter::Overview. .SH "AUTHOR" .IX Header "AUTHOR" Julian Mehnle