1Sendmail::PMilter::ContUesxetr(3C)ontributed Perl DocumeSnetnadtmiaoinl::PMilter::Context(3)
2
6 Sendmail::PMilter::Context - per-connection milter context
7
9 A Sendmail::PMilter::Context is the context object passed to milter
10 callback functions as the first argument, typically named "$ctx" for
11 convenience. This manual explains publicly accessible operations on
12 $ctx.
13
15 $ctx->getpriv
16 Returns the private data object for this milter instance, set by
17 $ctx->setpriv() (see below). Returns undef if setpriv has never
18 been called by this milter instance.
19 $ctx->getsymval(NAME)
21 Retrieves the macro symbol named NAME from the macros available
22 from the MTA for the current callback. This typically consists of
23 a one-letter macro name, or a multi-letter macro name enclosed in
24 {curly braces}. If the requested macro was not defined by the MTA
25 ny the time getsymval is called, returns undef.
26 Some common macros include the following. (Since milter is a
28 protocol first implemented in the Sendmail MTA, the macro names are
29 the same as those in Sendmail itself.)
30 $ctx->getsymval('_')
32 The remote host name and address, in standard SMTP "name
33 [address]" form.
34 $ctx->getsymval('i')
36 The MTA's queue ID for the current message.
37 $ctx->getsymval('j')
39 The MTA's idea of local host name.
40 $ctx->getsymval('{if_addr}')
42 The local address of the network interface upon which the
43 connection was received.
44 $ctx->getsymval('{if_name}')
46 The local hostname of the network interface upon which the
47 connection was received.
48 $ctx->getsymval('{mail_addr}')
50 The MAIL FROM: sender's address, canonicalized and angle bracket
51 stripped. (This is typically not the same value as the second
52 argument to the "envfrom" callback.) Will be defined to the
53 empty string '' if the client issued a MAIL FROM:<> null return
54 path command.
55 $ctx->getsymval('{rcpt_addr}')
57 The RCPT TO: recipient's address, canonicalized and angle bracket
58 stripped. (This is typically not the same value as the second
59 argument to the "envrcpt" callback.)
60 Not all macros may be available at all times, of course. Some
62 macros are only available after a specific phase is reached, and
63 some macros may only be available from certain MTA implementations.
64 Care should be taken to check for undef returns in order to cover
65 these cases.
66 $ctx->setpriv(DATA)
68 This is the place to store milter-private data that is sensitive to
69 the current SMTP client connection. Only one value can be stored,
70 so typically an arrayref or hashref is initialized in the "connect"
71 callback and set with $ctx->setpriv.
72 This value can be retrieved on subsequent callback runs with
74 $ctx->getpriv.
75 $ctx->setreply(RCODE, XCODE, MESSAGE)
77 Set an extended SMTP status reply (before returning SMFIS_REJECT or
78 SMFIS_TEMPFAIL). RCODE should be a short (4xx or 5xx) numeric
79 reply code, XCODE should be a long ('4.x.x' or '5.x.x') ESMTP reply
80 code, and MESSAGE is the full text of the message to send.
81 Example:
82 $ctx->setreply(451, '4.7.0', 'Cannot authenticate you right now');
84 return SMFIS_TEMPFAIL;
85 Note that after setting a reply with this method, the SMTP result
87 code comes from RCODE, not the difference between SMFIS_REJECT or
88 SMFIS_TEMPFAIL. However, for consistency, callbacks that set a 4xx
89 response code should use SMFIS_TEMPFAIL, and those that set a 5xx
90 code should return SMFIS_REJECT.
91 Returns a true value on success, undef on failure. In the case of
93 failure, typically only caused by bad parameters, a generic message
94 will still be sent based on the SMFIS_* return code.
95 $ctx->shutdown()
97 A special case of "$ctx->setreply()" which sets the short numeric
98 reply code to 421 and the ESMTP code to 4.7.0. Under Sendmail 8.13
99 and higher, this will close the MTA's communication channel
100 quickly, which should immediately result in a "close" callback and
101 end of milter execution. (However, Sendmail 8.11-8.12 will treat
102 this as a regular 4xx error and will continue processing the
103 message.)
104 Always returns a true value.
106 This method is an extension that is not available in the standard
108 Sendmail::Milter package.
109 $ctx->addheader(HEADER, VALUE)
111 Add header HEADER with value VALUE to this mail. Does not change
112 any existing headers with the same name. Only callable from the
113 "eom" callback.
114 Returns a true value on success, undef on failure.
116 $ctx->addrcpt(ADDRESS)
118 Add address ADDRESS to the list of recipients for this mail. Only
119 callable from the "eom" callback.
120 Returns a true value on success, undef on failure.
122 $ctx->chgheader(HEADER, INDEX, VALUE)
124 Change the INDEX'th header of name HEADER to the value VALUE. Only
125 callable from the "eom" callback.
126 Returns a true value on success, undef on failure.
128 $ctx->delrcpt(ADDRESS)
130 Remove address ADDRESS from the list of recipients for this mail.
131 The ADDRESS argument must match a prior argument to the "envrcpt"
132 callback exactly (case sensitive, and including angle brackets if
133 present). Only callable from the "eom" callback.
134 Returns a true value on success, undef on failure. A success
136 return does not necessarily indicate that the recipient was
137 successfully removed, but rather that the command was queued for
138 processing.
139 $ctx->progress()
141 Sends an asynchronous "progress" message to the MTA, which should
142 reset the MTA's internal communications timer. This can allow
143 longer than normal operations, such as a deliberate delay, to
144 continue running without dropping the milter-MTA connection. This
145 command can be issued at any time during any callback, although
146 issuing it during a "close" callback may trigger socket connection
147 warnings in Perl.
148 Always returns a true value.
150 This method is an extension that is not available in the standard
152 Sendmail::Milter package.
153 $ctx->quarantine(REASON)
155 Quarantine the current message in the MTA-defined quarantine area,
156 using the given REASON as a text string describing the quarantine
157 status. Only callable from the "eom" callback.
158 Returns a true value on success, undef on failure.
160 This method is an extension that is not available in the standard
162 Sendmail::Milter package.
163 $ctx->replacebody(BUFFER)
165 Replace the message body with the data in BUFFER (a scalar). This
166 method may be called multiple times, each call appending to the
167 replacement buffer. End-of-line should be represented by CR-LF
168 ("\r\n"). Only callable from the "eom" callback.
169 Returns a true value on success, undef on failure.
171 $ctx->setsender(ADDRESS)
173 Replace the envelope sender address for the given mail message.
174 This method provides an implementation to access the mlfi_setsender
175 method added to the libmilter library as part of the mlfi-setsender
176 project (http://www.sourceforge.net/projects/mlfi-setsender).
177 Returns a true value on success, undef on failure. A success
179 return does not necessarily indicate that the recipient was
180 successfully removed, but rather that the command was queued for
181 processing.
182
184 Sendmail::PMilter
185perl v5.32.0 2020-07-28 Sendmail::PMilter::Context(3)