NAME¶
Sendmail::PMilter::Context - per-connection milter context
DESCRIPTION¶
A Sendmail::PMilter::Context is the context object passed to milter callback
functions as the first argument, typically named "$ctx" for
convenience. This manual explains publicly accessible operations on $ctx.
METHODS¶
- $ctx->getpriv
- Returns the private data object for this milter instance,
set by $ctx-> setpriv() (see below). Returns undef if setpriv
has never been called by this milter instance.
- $ctx->getsymval(NAME)
- Retrieves the macro symbol named NAME from the macros
available from the MTA for the current callback. This typically consists
of a one-letter macro name, or a multi-letter macro name enclosed in
{curly braces}. If the requested macro was not defined by the MTA ny the
time getsymval is called, returns undef.
Some common macros include the following. (Since milter is a protocol first
implemented in the Sendmail MTA, the macro names are the same as those in
Sendmail itself.)
- $ctx->getsymval('_')
- The remote host name and address, in standard SMTP
"name [address]" form.
- $ctx->getsymval('i')
- The MTA's queue ID for the current message.
- $ctx->getsymval('j')
- The MTA's idea of local host name.
- $ctx->getsymval('{if_addr}')
- The local address of the network interface upon which the
connection was received.
- $ctx->getsymval('{if_name}')
- The local hostname of the network interface upon which the
connection was received.
- $ctx->getsymval('{mail_addr}')
- The MAIL FROM: sender's address, canonicalized and angle
bracket stripped. (This is typically not the same value as the second
argument to the "envfrom" callback.) Will be defined to the
empty string '' if the client issued a MAIL FROM:<> null return path
command.
- $ctx->getsymval('{rcpt_addr}')
- The RCPT TO: recipient's address, canonicalized and angle
bracket stripped. (This is typically not the same value as the second
argument to the "envrcpt" callback.)
Not all macros may be available at all times, of course. Some macros are only
available after a specific phase is reached, and some macros may only be
available from certain MTA implementations. Care should be taken to check for
undef returns in order to cover these cases.
- $ctx->setpriv(DATA)
- This is the place to store milter-private data that is
sensitive to the current SMTP client connection. Only one value can be
stored, so typically an arrayref or hashref is initialized in the
"connect" callback and set with $ctx->setpriv.
This value can be retrieved on subsequent callback runs with
$ctx->getpriv.
- $ctx->setreply(RCODE, XCODE, MESSAGE)
- Set an extended SMTP status reply (before returning
SMFIS_REJECT or SMFIS_TEMPFAIL). RCODE should be a short (4xx or 5xx)
numeric reply code, XCODE should be a long ('4.x.x' or '5.x.x') ESMTP
reply code, and MESSAGE is the full text of the message to send. Example:
$ctx->setreply(451, '4.7.0', 'Cannot authenticate you right now');
return SMFIS_TEMPFAIL;
Note that after setting a reply with this method, the SMTP result code comes
from RCODE, not the difference between SMFIS_REJECT or SMFIS_TEMPFAIL.
However, for consistency, callbacks that set a 4xx response code should
use SMFIS_TEMPFAIL, and those that set a 5xx code should return
SMFIS_REJECT.
Returns a true value on success, undef on failure. In the case of failure,
typically only caused by bad parameters, a generic message will still be
sent based on the SMFIS_* return code.
- $ctx->shutdown()
- A special case of "$ctx->setreply()" which
sets the short numeric reply code to 421 and the ESMTP code to 4.7.0.
Under Sendmail 8.13 and higher, this will close the MTA's communication
channel quickly, which should immediately result in a "close"
callback and end of milter execution. (However, Sendmail 8.11-8.12 will
treat this as a regular 4xx error and will continue processing the
message.)
Always returns a true value.
This method is an extension that is not available in the standard
Sendmail::Milter package.
- $ctx->addheader(HEADER, VALUE)
- Add header HEADER with value VALUE to this mail. Does not
change any existing headers with the same name. Only callable from the
"eom" callback.
Returns a true value on success, undef on failure.
- $ctx->addrcpt(ADDRESS)
- Add address ADDRESS to the list of recipients for this
mail. Only callable from the "eom" callback.
Returns a true value on success, undef on failure.
- $ctx->chgheader(HEADER, INDEX, VALUE)
- Change the INDEX'th header of name HEADER to the value
VALUE. Only callable from the "eom" callback.
Returns a true value on success, undef on failure.
- $ctx->delrcpt(ADDRESS)
- Remove address ADDRESS from the list of recipients for this
mail. The ADDRESS argument must match a prior argument to the
"envrcpt" callback exactly (case sensitive, and including angle
brackets if present). Only callable from the "eom" callback.
Returns a true value on success, undef on failure. A success return does not
necessarily indicate that the recipient was successfully removed, but
rather that the command was queued for processing.
- $ctx->progress()
- Sends an asynchronous "progress" message to the
MTA, which should reset the MTA's internal communications timer. This can
allow longer than normal operations, such as a deliberate delay, to
continue running without dropping the milter-MTA connection. This command
can be issued at any time during any callback, although issuing it during
a "close" callback may trigger socket connection warnings in
Perl.
Always returns a true value.
This method is an extension that is not available in the standard
Sendmail::Milter package.
- $ctx->quarantine(REASON)
- Quarantine the current message in the MTA-defined
quarantine area, using the given REASON as a text string describing the
quarantine status. Only callable from the "eom" callback.
Returns a true value on success, undef on failure.
This method is an extension that is not available in the standard
Sendmail::Milter package.
- $ctx->replacebody(BUFFER)
- Replace the message body with the data in BUFFER (a
scalar). This method may be called multiple times, each call appending to
the replacement buffer. End-of-line should be represented by CR-LF
("\r\n"). Only callable from the "eom" callback.
Returns a true value on success, undef on failure.
- $ctx->setsender(ADDRESS)
- Replace the envelope sender address for the given mail
message. This method provides an implementation to access the
mlfi_setsender method added to the libmilter library as part of the
mlfi-setsender project
(http://www.sourceforge.net/projects/mlfi-setsender).
Returns a true value on success, undef on failure. A success return does not
necessarily indicate that the recipient was successfully removed, but
rather that the command was queued for processing.
SEE ALSO¶
Sendmail::PMilter