/usr/share/doc/libbobcat3-dev/man/milter.3.html is in libbobcat-dev 3.19.01-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 | <html><head>
<title>FBB::Milter</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::Milter</h1>
<h2>libbobcat-dev_3.19.01-x.tar.gz</h2>
<h2>2005-2013</h2>
<html><head>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1></h1>
<html><head>
<title>FBB::Milter(3bobcat)</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::Milter(3bobcat)</h1>
<h2>libbobcat-dev_3.19.01-x.tar.gz Milter interface</h2>
<h2>2005-2013</h2>
<p>
<h2>NAME</h2>FBB::Milter - Interface to the sendmail mail filter facilities
<p>
<h2>SYNOPSIS</h2>
<strong>#include <bobcat/milter></strong><br>
Linking option: <em>-lmilter -lbobcat</em>
<p>
<h2>DESCRIPTION</h2>
<p>
<strong>Milter</strong> defines an abtract base class interfacing to the sendmail mail
filter (milter) facilities. It defines a <strong>C++</strong> interface, based on the
assumption that a single mail filter program does not implement multiple mail
filters. The traditional sendmail <strong>C</strong>-based Milter API uses a (<em>SMFICTX</em>)
pointer representing a mail connection, and a pointer to connection-specific
`private' data, requiring the Milter constructor to perform quite a few
administrative tasks. While acceptable in a <strong>C</strong> environment these
administratve tasks distract from the main task: the Milter's mail filtering
functionality. The <strong>FBB::Milter</strong> class hides these administrative tasks from
the programmer, who is then able to concentrate on filtering mail. The main
benefits of <strong>Milter</strong> are therefore
<ul>
<li> Basic administration is performed by the <strong>Milter</strong> class
<li> The class' interface is more <strong>C++</strong> like than the raw <strong>C</strong>
interface offered by the milter API.
<li> Administration, allocation and communicating of connection specific
data is no longer required
<li> It is not normally necessary to use connection-specific data, like a
pointer identifying the connection, anymore when implementing the Milter.
<li> <strong>Milter</strong> uses current-day design patterns enforcing principles of
reuable software, thus simplifying the construction of the actual Milter.
</ul>
To activate a milter from the <em>sendmail.mc</em> configuration file, use,
e.g., <em>INPUT_MAIL_FILTER(`name', `S=socket')</em>, where <em>name</em> is the
milter's name, and <em>socket</em> is the name of the socket. See also the
<em>setConnection</em> member below.
<p>
<h2>NAMESPACE</h2>
<strong>FBB</strong><br>
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace <strong>FBB</strong>.
<p>
<h2>INHERITS FROM</h2>
-
<p>
<h2>ENUMERATIONS</h2>
<p>
The class defines four enumerations. One enumeration is used to indicate
the callback-functions that need to be called, the second one renames the
flags that can be passed to sendmail to indicate which actions the milter is
allowed to perform. The third one defines status values that may be used to
inform sendmail how to further process a message. The fourth one defines
return values. The enumerations are:
<p>
<strong>enum CallBack</strong><br>
This enumeration holds the following values:
<ul>
<li> <strong>CONNECT</strong>:<br>
Indicates that the milter defines (overrides) the
connection-functionality. This is the first callback function that can be
called by sendmail.
<li> <strong>HELO</strong>:<br>
Indicates that the milter defines (overrides) the
helo-functionality. This indicates that the <em>helo</em> function should be
called by sendmail, providing the milter with information about the connecting
client.
<li> <strong>SENDER</strong>:<br>
Indicates that the milter defines (overrides) the
sender-functionality. This indicates that the <em>sender</em> function should be
called by sendmail, providing the milter with the sender's envelope
information.
<li> <strong>RECIPIENT</strong>:<br>
Indicates that the milter defines (overrides) the
recipient-functionality. This indicates that the <em>recipient</em> function
should be called by sendmail, providing the milter with the recipient's
envelope information.
<li> <strong>HEADER</strong>:<br>
Indicates that the milter defines (overrides) the
header-functionality. This indicates that the <em>header</em> function
should be called by sendmail for each mail header that is used in the current
mail message.
<li> <strong>EOH</strong>:<br>
Indicates that the milter defines (overrides) the
end-of-header-functionality. This indicates that the <em>eoh</em> function
should be called by sendmail once all header lines have been processed.
<li> <strong>BODY</strong>:<br>
Indicates that the milter defines (overrides) the
body-functionality. This indicates that the <em>body</em> function
should be called by sendmail, offering the mail-body to the milter.
<li> <strong>EOM</strong>:<br>
Indicates that the milter defines (overrides) the
end-of-message-functionality. This indicates that the <em>eom</em> function
should be called by sendmail, once all elements of the e-mail message have
been processed.
<li> <strong>ABORT</strong>:<br>
Indicates that the milter defines (overrides) the
abort-functionality. The <em>abort</em> function may be called by sendmail before
<em>eom</em> is called. It should reclaim all resources used by the message, but
not delete any memory allocated by the milter, as this is <em>close</em>'s job.
<li> <strong>CLOSE</strong>:<br>
Indicates that the milter defines (overrides) the
close-functionality. The <em>close</em> function should delete all (connection
specific) memory allocated by the milter. It may be called `out-of-order',
i.e. even before <em>connect</em> is called and developers should anticipate this
possibility when crafting their <em>close</em> code. In particular, it is
incorrect to assume the private context pointer will be something other than
0 in this callback.
<li> <strong>UNKNOWN</strong>:<br>
Currently not used. Reserved for versions exceeding version 2 of the
sendmail milter API
<li> <strong>DATA</strong>:<br>
Currently not used. Reserved for versions exceeding version 3 of the
sendmail milter API
<li> <strong>ALL_CALLBACKS</strong>:<br>
Shortcut to indicate all callback facilities. The <em>CallBack</em> values
are bit-flags. The <em>bit_or</em> operator may be used to combine them, and the
<em>bit_not</em> operator may be used to remove a flag from <em>ALL_CALLBACKS</em>
(e.g., <em>ALL_CALLBACKS && ~ABORT</em>).
</ul>
<p>
<strong>enum Flags</strong><br>
This enumeration holds the following values:
<ul>
<li> <strong>NO_FLAGS</strong>:<br>
No flags are defined.
<li> <strong>ADD_HEADERS</strong>:<br>
This flag indicates that the milter is allowed to add headers to the
current e-mail message.
<li> <strong>ADD_RECIPIENTS</strong>:<br>
This flag indicates that the milter is allowed to add recipients to the
current e-mail message.
<li> <strong>CHANGE_BODY</strong>:<br>
This flag indicates that the milter is allowed to modify the message's
body contents.
<li> <strong>CHANGE_HEADERS</strong>:<br>
This flag indicates that the milter is allowed to change headers of
the current e-mail message.
<li> <strong>DELETE_RECIPIENTS</strong>:<br>
This flag indicates that the milter is allowed to remove recipients
from the current e-mail message.
<li> <strong>QUARANTINE</strong>:<br>
This flag indicates that the milter is allowed to request sendmail to
quarantine the current e-mail message.
<li> <strong>ALL_FLAGS</strong>:<br>
Shortcut to indicate all callback facilities. The <em>Flags</em> values
are bit-flags. The <em>bit_or</em> operator may be used to combine them, and the
<em>bit_not</em> operator may be used to remove a flag from <em>ALL_FLAGS</em>
(e.g., <em>ALL_FLAGS && ~QUARANTINE</em>).
</ul>
<p>
<strong>Status</strong><br>
This enumeration simplifies the extended <em>SMFIS_</em> values used by the
<strong>C</strong> API. These values may be used to return <em>sfsistat</em> values:
<ul>
<li> <strong>ACCEPT</strong>:<br>
This value is equal to <em>SMFIS_ACCEPT</em>, indicating that Sendmail
should accept the message. For a connection-oriented callback (see below at
<strong>PROTECTED VIRTUAL MEMBER FUNCTIONS</strong>), accept this connection without
further filter processing, call <em>close</em> (see below). For other callbacks:
accept this message without further filtering.
<li> <strong>CONTINUE</strong>:<br>
This value is equal to <em>SMFIS_CONTINUE</em>, indicating that Sendmail
should continue processing. This is the default for all callback functions
which are not overridden by the class derived from <strong>Milter</strong>.
<li> <strong>DISCARD</strong>:<br>
This value is equal to <em>SMFIS_DISCARD</em>, indicating that Sendmail
should discard the mail message. It should not be returned by a
connection-oriented callback. For other callbacks: the message is accepted,
but silently discarded.
<li> <strong>REJECT</strong>:<br>
This value is equal to <em>SMFIS_REJECT</em>, indicating that Sendmail
should reject the mail message. For a connection-oriented callback, reject
this connection; call <em>close</em>. For a message-oriented callback (except
for <em>eom</em> or <em>abort, see below</em>), reject this message. For a
recipient-oriented callback, reject the current recipient (but continue
processing the current message).
<li> <strong>TEMPFAIL</strong>:<br>
This value is equal to <em>SMFIS_TEMPFAIL</em>, indicating that Sendmail
should return a `temporary unavailable' message to the sender of the mail
message. For a message-oriented callback (except <em>sender</em>, see below),
fail for this message. For a connection-oriented callback, fail for this
connection and call <em>close</em>. For a recipient-oriented callback, only fail
for the current recipient and continue message processing.
</ul>
<p>
<strong>Return</strong><br>
This enumeration simplifies the extended <em>MI_</em> values used by the
<strong>C</strong> API. Most return values used by the <strong>Milter</strong> class, however, are
<em>bool</em> values. The <em>Return</em> values are:
<ul>
<li> <strong>FAILURE</strong>:<br>
This value is equal to <em>MI_FAILURE</em>, indicating that a <strong>C</strong>-api
function failed to perform its task.
<li> <strong>SUCCESS</strong>:<br>
This value is equal to <em>MI_SUCCESS</em>, indicating that a <strong>C</strong>-api
function succeeded in performing its task.
</ul>
<p>
<h2>CONSTRUCTORS</h2>
<p>
The default- and copy constructors are available for derived classes. They
perform no actions.
<p>
<h2>PUBLIC STATIC MEMBER FUNCTIONS</h2>
<p>
These functions form the heart of the <strong>Milter</strong> base-class. They can be
called to initialize, start and stop the Milter.
<ul>
<li> <strong>void initialize(std::string const &name,
Milter &milter,
callback_set callbacks = CONNECT,
flag_set flags = NO_FLAGS)</strong>:<br>
This function initializes the Milter's administration. It expects the
name of the mailfilter as its first argument. Its second argument is a
reference to a <em>Milter</em> object. Since <strong>Milter</strong> is an abstract base class
the actual object is always an object of a class derived from <strong>Milter</strong>. Its
third argument specifies the callbacks to call for this milter. By default the
<em>connect</em> callback will be called. Note that the <em>close</em> callback is
not called by default. This is ok, since the <strong>Milter</strong> object doesn't have to
cleanup `private' data, as is normal with the <strong>C</strong> API. The last argument
defines flags, specifying the Milter's capabilities.
<li> <strong>std::string const &name()</strong>:<br>
This function returns the milter's name.
<li> <strong>bool start()</strong>:<br>
This member function calls <em>smfi_main</em>, controlling the milter's
event loop. It returns <em>true</em> if the event-loop is successfully terminated.
<li> <strong>void stop()</strong>:<br>
This member function terminates the milter's event loop, after
finishing all threads. Following this call <em>start</em> may be called again to
continue the milter.
</ul>
<p>
<h2>PROTECTED VIRTUAL MEMBER FUNCTIONS</h2>
<p>
The remaining functionality of the class <em>Milter</em> is useful only for
Milter-implementations in classes derived from <strong>Milter</strong>. The following
members can be overridden by derived classes. Note that <em>clone</em> <em>must</em>
be overridden. Except for <em>clone</em>, all the members in this sections are
<em>callback</em> functions. I.e., the MTA will call them to process parts of the
mail message. Recipient-, message-, and connection-oriented callbacks are
distinguished.
<p>
The recipient-oriented callback (<em>recipient</em>, see below) may affect
the processing of a single message to a single recipient. Connection-oriented
callbacks (<em>connect, helo</em> and <em>close</em>) affect the processing of the
entire connection (during which multiple messages may be delivered to multiple
sets of recipients). The remaining callbacks are message-oriented, affecting
the processing of a single message to all its recipients.
<p>
<ul>
<li> <strong>virtual sfsistat abort()</strong>:<br>
This message-oriented member may be called at any time during message
processing (i.e. between some message-oriented routine and
<em>eom</em>). <em>abort</em> reclaim any resources allocated on a per-message basis
(which are <em>not</em> the connection specific data, which should be handled by
the derived class' destructor), and must be tolerant of being called between
any two message-oriented callbacks. <em>abort</em> is only called if the message
is aborted outside the filter's control and the filter has not completed its
message-oriented processing. For example, if a filter has already returned
<em>ACCEPT, REJECT</em>, or <em>DISCARD</em> from a message-oriented routine,
<em>abort</em> will not be called even if the message is later aborted outside
its control.
<li> <strong>virtual sfsistat body(unsigned char *text, size_t length)</strong>:<br>
This message-oriented member is called zero or more times between
<em>eoh</em> and <em>eom</em>. <em>text</em> points to a sequence of bytes. It is not
necessarily a 0-terminated. Moreover, the sequence may contain 0-characters.
Since message bodies can be very large, defining <em>body</em> can significantly
impact filter performance. End-of-lines are represented as received from SMTP
(normally CR/LF). Later filters will see body changes made by earlier ones,
and message bodies may be sent in multiple chunks, with one call to <em>body</em>
per chunk.
<p>
<li> <strong>virtual Milter *clone() const = 0</strong>:<br>
This pure virtual function must be implemented by derived classes to
return a newly allocated copy of the derived object passed to the
<em>initialize</em> static member. It is used by the standard `virtual
constructor' design pattern. The destruction of the allocated object is the
responsibility of <em>clone</em>'s caller.
<p>
<li> <strong>virtual sfsistat close()</strong>:<br>
This connection-oriented member is always called once at the end of
each connection. It may be called "out-of-order", i.e. before even the
<em>connect</em> is called. After a connection is established by the MTA to the
filter, if the MTA decides this connection's traffic will be discarded
(e.g. via an access_db result), no data will be passed to the filter from the
MTA until the client closes down. At that time, <em>close</em> is called. It can
therefore be the only callback ever used for a given connection, and
developers should anticipate this possibility when crafting their <em>close</em>
code. The member <em>close</em> is called on close even if the previous mail
transaction was aborted.
<p>
<li> <strong>virtual sfsistat connect(char *hostname, _SOCK_ADDR *hostaddr)</strong>:<br>
This connection-oriented member may be called once, at the start of
each SMTP connection. The parameter <em>hostname</em> is he host name of the
message sender, as determined by a reverse lookup on the host address. If the
reverse lookup fails, hostname will contain the message sender's IP address
enclosed in square brackets (e.g. <em>[a.b.c.d]</em>). The parameter <em>hostaddr</em>
is the host address, as determined by a <strong>getpeername</strong>(2) call on the SMTP
socket. It is 0 if the type is not supported in the current version or if the
SMTP connection is made via stdin.
<p>
<li> <strong>virtual sfsistat data()</strong>:<br>
Not yet supported. Will be available with libmilter versions beyond 3.
<p>
<li> <strong>virtual sfsistat eoh()</strong>:<br>
This message-oriented member is called once after all headers have
been processed.
<p>
<li> <strong>virtual sfsistat eom()</strong>:<br>
This message-oriented member is called once after all calls to
<em>body</em> for a given message have been completed. Note that only in this
function modifications to the message headers, body, and envelope can be made
(see the <em>add-, change-</em> and <em>delete-</em> members listed below).
<p>
<li> <strong>virtual sfsistat header(char *headerf, char *headerv)</strong>:<br>
This message-oriented member is called zero or more times between
<em>recipient</em> and <em>eoh</em>, once per message header. The <em>headerf</em>
parameter contains the text of the header, the <em>headerv</em> parameter contains
its value. E.g., if an e-mail message contains the following headers:
<pre>
From: sender <f@example.com>
Subject:no
</pre>
then <em>header</em> will be called twice with the following values for,
respectively <em>headerf</em> and <em>headerv</em>:
<pre>
First header: "From", " sender <f@example.com>"
Second header: "Subject", "no"
</pre>
Further details about header information is given in RFC 882.
<p>
<li> <strong>virtual sfsistat helo(char *helohost)</strong>:<br>
This connection-oriented member is called whenever the client sends a
HELO/EHLO command. It may therefore be called between zero and three
times. The <em>helohost</em> parameter should be the domain name of the sending
host (but is, in practice, anything the sending host wants to send).
<p>
<li> <strong>virtual sfsistat recipient(char **argv)</strong>:<br>
This recipient-oriented member is called once per recipient, hence one
or more times per message, immediately after <em>sender</em>. The parameter
<em>argv</em> is a 0-terminated array of pointers to SMTP command arguments;
argv[0] is guaranteed to be the recipient address. Later arguments are the
ESMTP arguments. TEMPFAIL may be returned indicate that sendmail should return
a temporary failure for this particular recipient; further recipients may
still be sent, <em>abort</em> is not called. REJECT will reject this particular
recipient; further recipients may still be sent, <em>abort</em> is not called.
DISCARD will accept (but discard) the message, <em>abort</em> will be called.
ACCEPT will accept recipient, <em>abort</em> will not be called. More details on
ESTMP responses, are described in RFC 1869.
<p>
<li> <strong>virtual sfsistat sender(char **argv)</strong>:<br>
This message-oriented member is called once at the beginning of each
message, before <em>recipient</em>. argv[0] is guaranteed to be the sender's
envelope address. Later arguments are the ESMTP arguments. TEMPFAIL may be
returned, indicating that sendmail should return a temporary failure for this
particular message, <em>abort</em> is not called. REJECT will reject this
message, <em>abort</em> is not called. DISCARD will accept (but discard) the
message, <em>abort</em> will be called. ACCEPT will accept recipient,
<em>abort</em> will not be called. More details on ESTMP responses, are described
in RFC 1869.
<p>
<li> <strong>virtual sfsistat unknown(char *ptr)</strong>:<br>
Not yet supported. Will be available with libmilter versions beyond 2.
</ul>
<p>
<h2>PROTECTED MEMBER FUNCTIONS</h2>
<p>
The following members are non-virtual. They can be called by members of
classes derived from <strong>Milter</strong>:
<ul>
<li> <strong>bool addHeader(std::string const &hdrName,
std::string const &hdrValue)</strong>:<br>
This member may only be called from <em>eom</em>, and the flag
<em>ADD_HEADERS</em> must have been specified or it will fail. The <em>hdrName</em> and
<em>hdrValue</em> must be non-empty strings. Each line of the header must be under
2048 characters and should be under 998 characters. If longer headers are
needed, make them multi-line. To make a multi-line header, insert a line feed
(<em>\n</em>) followed by at least one whitespace character such as a space or tab
(<em>\t</em>). The line feed should <em>not</em> be preceded by a carriage return. It is
the filter writer's responsibility to ensure that no standards are violated.
<li> <strong>bool addRecipient(std::string const &rcptName)</strong>:<br>
This member may only be called from <em>eom</em>, and the flag
<em>ADD_RECIPIENTS</em> must have been specified or it will fail.
<li> <strong>bool changeHeader(std::string const &hdrName,
size_t headerNr, std::string const &hdrValue)</strong>:<br>
This member may only be called from <em>eom</em>, and the flag
<em>CHANGE_HEADERS</em> must have been specified or it will fail. See
<em>addHeader</em> for the header-requirements. The <em>headerNr</em> parameter is a
1-based header index value. A <em>headerNr</em> value of 1 will modify the first
occurrence of a header named <em>hdrValue</em>. If <em>headerNr</em> is greater than the
number of times <em>hdrName</em> appears, a new <em>hdrName</em>-header will be
added. If <em>hdrValue</em> is empty, the header is deleted.
<li> <strong>bool deleteRecipient(std::string const &rcptName)</strong>:<br>
This member may only be called from <em>eom</em>, and the flag
<em>DELETE_RECIPIENTS</em> must have been specified or it will fail.
This member removes the named recipient from the current message's
envelope.
<li> <strong>SMFICTX *id() const</strong>:<br>
This member may be called by the Milter object to obtain a pointer
identifying its sendmail-connection. Normally it should not be necessary to
call this member.
<li> <strong>bool insertHeader(size_t hdrIdx, std::string const &hdrName,
std::string const &hdrValue)</strong>:<br>
This member may only be called from <em>eom</em>, and the flag
<em>ADD_HEADERS</em> must have been specified or it will fail. See
<em>addHeader</em> for the header-requirements. The <em>headerNr</em> parameter is a
header index value. A <em>headerNr</em> value of 0 will insert this header as the
first of the <em>hdrName</em> headers. If <em>headerNr</em> is greater than the
number of times <em>hdrName</em> appears, a new <em>hdrName</em>-header will be
added.
<li> <strong>bool openSocket(bool removeIfTrue = true)</strong>:<br>
This member should be called before <em>start</em> is called.
This member attempts to create the socket specified by
<em>setConnection</em> (see below). This allows the calling application to ensure
that the socket can be created, possibly changing its protection (access
rights) before the milter starts its work. If this member is not called, it
will be called implicitly when <em>run</em> is started. It returns <em>true</em> if
the socket could be created.
<li> <strong>bool quarantine(std::string const &reason)</strong>:<br>
This member may only be called from <em>eom</em> and causes the MTA to
quarantines the message using the given reason.
<li> <strong>bool replaceBody(std::string const &body)</strong>:<br>
This member may only be called from <em>eom</em>, and the flag
<em>CHANGE_BODY</em> must have been specified or it will fail. It may be called
multiple times in which case the various body contents are concatenated in the
final message. Newlines should be coded as CRLF.
<li> <strong>bool setBacklog(size_t backlog = 5)</strong>:<br>
This member should be called before <em>start</em> is called.
Sets the incoming socket backlog used by <strong>listen</strong>(2). If
<em>setBacklog</em> is not called, the operating system default is used. The
function returns <em>false</em> if the backlog could not be set as requested. It
is the responsibility of the programmer not to call this function with a 0
argument.
<li> <strong>bool setConnection(std::string const &name)</strong>:<br>
This member should be called before <em>start</em> is called.
Sets the socket through which the filter communicates with sendmail.
The socket may be specified using one of the following variants:<br>
<em>{unix|local}:/path/to/file</em> - A named pipe;<br>
<em>net:port@{hostname|ip-address}</em> - An IPV4 socket;<br>
<em>inet6:port@{hostname|ip-address}</em> - An IPV6 socket.<br>
<p>
If possible, filters should not run as root when communicating over
unix/local domain sockets.
<p>
Unix/local sockets should have their permissions set to 0600 (read/write
permission only for the socket's owner) or 0660 (read/write permission for the
socket's owner and group) which is useful if the sendmail RunAsUser option is
used. The permissions for a unix/local domain socket are determined as usual
by umask, which should be set to 007 or 077.
<p>
Possible failure of this function cannot be determined from its return
value. Rather, <em>run</em> will fail.
<li> <strong>setReply(std::string const &rcode, std::string const &xcode = "",
std::string const &msg = "")</strong>:<br>
This member sets the default SMTP error reply code. It may be called
from any callback member, except <em>connect</em>. The parameter <em>rcode</em> should
be a he three-digit (RFC 821/2821) SMTP reply code and it must be a valid 4XX
or 5XX reply code. The parameter <em>xcode</em>, when specified, must be a extended
(RFC 1893/2034) reply code. The parameter <em>msg</em> may be an additional textual
message. The <strong>Milter</strong> class has no member comparable to the libmilter API
function <em>smfi_setmlreply</em>. the <strong>Milter</strong> class.
<li> <strong>void setTimeout(size_t seconds = 7210)</strong>:<br>
This member should be called before <em>start</em> is called.
Sets the number of seconds libmilter will wait for an MTA connection
before timing out a socket. If <em>setTimeout</em> is not called, a default
timeout of 7210 seconds is used. It is the responsibility of the programmer
not to call this function with an argument equal to 0.
<li> <strong>char const *symval(std::string const &name) const</strong>:<br>
This member returns the value of a specific sendmail macro. The
<em>name</em> parameter should be set to he name of a sendmail macro . Single letter
macros can optionally be enclosed in braces (<em>{</em> and <em>}</em>), longer macro
names must be enclosed in braces, just as in a sendmail.cf file.0 is returned
if the macro is not defined. By default, the following macros are valid in
the given contexts:<br>
for <em>connect</em>: <em>daemon_name, if_name, if_addr, j, _</em>;<br>
for <em>helo</em>: <em>tls_version, cipher, cipher_bits, cert_subject,
cert_issuer</em>;<br>
for <em>sender</em>: <em>i, auth_type, auth_authen, auth_ssf, auth_author,
mail_mailer, mail_host, mail_addr</em>;<br>
for <em>recipient</em>: <em>rcpt_mailer, rcpt_host, rcpt_addr</em>.<br>
All macros stay in effect from the point they are received until the end
of the connection for the first two sets, the end of the message for the third
(<em>sender</em>), and just for each recipient for the final set
(<em>recipient</em>).<br>
The following macros may be specified in the sendmail.mc configuration
file:<br>
<em>define(`confMILTER_MACROS_CONNECT', `m1', ...)</em>,
<em>define(`confMILTER_MACROS_HELO', ...)</em>,
<em>define(`confMILTER_MACROS_ENVFROM', ...)</em>,
<em>define(`confMILTER_MACROS_ENVRCPT', ...)</em>, where <em>`m1', ...</em> represents a
comma separated list of returnable macros. Single letter macros can
optionally be enclosed in braces (<em>{</em> and <em>}</em>), longer macro names must be
enclosed in braces.
<li> <strong>bool wait()</strong>:<br>
This member may only be called from <em>eom</em> and tells the MTA that
the filter is still working on a message, causing the MTA to re-start its
timeouts.
</ul>
<p>
<h2>EXAMPLE</h2>
To do
<p>
<h2>FILES</h2>
<em>bobcat/milter</em> - defines the class interface
<p>
<h2>SEE ALSO</h2>
<strong>bobcat</strong>(7), <strong>getpeername</strong>(2), <strong>listen</strong>(2), <br>
<em>http://www.milter.org</em> (e.g.,
<em>http://www.milter.org/developers/api</em>)<br>
<em>http://sendmail.org/m4/readme.html</em><br>
<em>http://rfc.net/rfc821.html</em><br>
<em>http://rfc.net/rfc822.html</em><br>
<em>http://rfc.net/rfc1869.html</em><br>
<em>http://rfc.net/rfc1893.html</em><br>
<em>http://rfc.net/rfc2034.html</em><br>
<em>http://rfc.net/rfc2821.html</em><br>
<em>/usr/include/libmilter/mfapi.h</em>
<p>
<h2>BUGS</h2>
<em>-lmilter</em> must be specified before <em>-lbobcat</em>.
<p>
<h2>DISTRIBUTION FILES</h2>
<ul>
<li> <em>bobcat_3.19.01-x.dsc</em>: detached signature;
<li> <em>bobcat_3.19.01-x.tar.gz</em>: source archive;
<li> <em>bobcat_3.19.01-x_i386.changes</em>: change log;
<li> <em>libbobcat1_3.19.01-x_*.deb</em>: debian package holding the
libraries;
<li> <em>libbobcat1-dev_3.19.01-x_*.deb</em>: debian package holding the
libraries, headers and manual pages;
<li> <em>http://sourceforge.net/projects/bobcat</em>: public archive location;
</ul>
<p>
<h2>BOBCAT</h2>
Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
<p>
<h2>COPYRIGHT</h2>
This is free software, distributed under the terms of the
GNU General Public License (GPL).
<p>
<h2>AUTHOR</h2>
Frank B. Brokken (<strong>f.b.brokken@rug.nl</strong>).
<p>
|