Per-connection milter context
A Sendmail::PMilter::Context is the context object passed to milter callback functions as the first argument, typically named \*(L"$ctx\*(R" for convenience. This manual explains publicly accessible operations on $ctx.
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. Retrieves the macro symbol named \s-1NAME\s0 from the macros available from the \s-1MTA\s0 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 \s-1MTA\s0 ny the time getsymval is called, returns undef. Some common macros include the following. (Since milter is a protocol first implemented in the Sendmail \s-1MTA\s0, the macro names are the same as those in Sendmail itself.)
The remote host name and address, in standard \s-1SMTP\s0 \*(L"name [address]\*(R" form. The \s-1MTA\s0's queue \s-1ID\s0 for the current message. The \s-1MTA\s0's idea of local host name. The local address of the network interface upon which the connection was received. The local hostname of the network interface upon which the connection was received. The \s-1MAIL\s0 \s-1FROM:\s0 sender's address, canonicalized and angle bracket stripped. (This is typically not the same value as the second argument to the \*(L"envfrom\*(R" callback.) Will be defined to the empty string '' if the client issued a \s-1MAIL\s0 FROM:<> null return path command. The \s-1RCPT\s0 \s-1TO:\s0 recipient's address, canonicalized and angle bracket stripped. (This is typically not the same value as the second argument to the \*(L"envrcpt\*(R" 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 \s-1MTA\s0 implementations. Care should be taken to check for undef returns in order to cover these cases.
This is the place to store milter-private data that is sensitive to the current \s-1SMTP\s0 client connection. Only one value can be stored, so typically an arrayref or hashref is initialized in the \*(L"connect\*(R" callback and set with $ctx->setpriv. This value can be retrieved on subsequent callback runs with $ctx->getpriv. Set an extended \s-1SMTP\s0 status reply (before returning \s-1SMFIS_REJECT\s0 or \s-1SMFIS_TEMPFAIL\s0). \s-1RCODE\s0 should be a short (4xx or 5xx) numeric reply code, \s-1XCODE\s0 should be a long ('4.x.x' or '5.x.x') \s-1ESMTP\s0 reply code, and \s-1MESSAGE\s0 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 \s-1SMTP\s0 result code comes from \s-1RCODE\s0, not the difference between \s-1SMFIS_REJECT\s0 or \s-1SMFIS_TEMPFAIL\s0. However, for consistency, callbacks that set a 4xx response code should use \s-1SMFIS_TEMPFAIL\s0, and those that set a 5xx code should return \s-1SMFIS_REJECT\s0. 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. A special case of \*(C`$ctx->setreply()\*(C' which sets the short numeric reply code to 421 and the \s-1ESMTP\s0 code to 4.7.0. Under Sendmail 8.13 and higher, this will close the \s-1MTA\s0's communication channel quickly, which should immediately result in a \*(L"close\*(R" 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. Add header \s-1HEADER\s0 with value \s-1VALUE\s0 to this mail. Does not change any existing headers with the same name. Only callable from the \*(L"eom\*(R" callback. Returns a true value on success, undef on failure. Add address \s-1ADDRESS\s0 to the list of recipients for this mail. Only callable from the \*(L"eom\*(R" callback. Returns a true value on success, undef on failure. Change the \s-1INDEX\s0'th header of name \s-1HEADER\s0 to the value \s-1VALUE\s0. Only callable from the \*(L"eom\*(R" callback. Returns a true value on success, undef on failure. Remove address \s-1ADDRESS\s0 from the list of recipients for this mail. The \s-1ADDRESS\s0 argument must match a prior argument to the \*(L"envrcpt\*(R" callback exactly (case sensitive, and including angle brackets if present). Only callable from the \*(L"eom\*(R" 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. Sends an asynchronous \*(L"progress\*(R" message to the \s-1MTA\s0, which should reset the \s-1MTA\s0'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 \*(L"close\*(R" 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. Quarantine the current message in the MTA-defined quarantine area, using the given \s-1REASON\s0 as a text string describing the quarantine status. Only callable from the \*(L"eom\*(R" 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. Replace the message body with the data in \s-1BUFFER\s0 (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 (\*(L"\r\n\*(R"). Only callable from the \*(L"eom\*(R" callback. Returns a true value on success, undef on failure. 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.
Sendmail::PMilter