Milter defines an abtract base class interfacing to the sendmail mail
filter (milter) facilities. It defines a C++ interface, based on the
assumption that a single mail filter program does not implement multiple mail
filters. The traditional sendmail C-based Milter API uses a (SMFICTX)
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 C environment these
administratve tasks distract from the main task: the Milter's mail filtering
functionality. The FBB::Milter class hides these administrative tasks from
the programmer, who is then able to concentrate on filtering mail. The main
benefits of Milter are therefore
Basic administration is performed by the Milter class
The class' interface is more C++ like than the raw C
interface offered by the milter API.
Administration, allocation and communicating of connection specific
data is no longer required
It is not normally necessary to use connection-specific data, like a
pointer identifying the connection, anymore when implementing the Milter.
Milter uses current-day design patterns enforcing principles of
reuable software, thus simplifying the construction of the actual Milter.
To activate a milter from the sendmail.mc configuration file, use,
e.g., INPUT_MAIL_FILTER(`name', `S=socket'), where name is the
milter's name, and socket is the name of the socket. See also the
setConnection() member below.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
INHERITS FROM
-
ENUMERATIONS
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:
enum CallBack
This enumeration holds the following values:
CONNECT:
Indicates that the milter defines (overrides) the
connection-functionality. This is the first callback function that can be
called by sendmail.
HELO:
Indicates that the milter defines (overrides) the
helo-functionality. This indicates that the helo() function should be
called by sendmail, providing the milter with information about the connecting
client.
SENDER:
Indicates that the milter defines (overrides) the
sender-functionality. This indicates that the sender() function should be
called by sendmail, providing the milter with the sender's envelope
information.
RECIPIENT:
Indicates that the milter defines (overrides) the
recipient-functionality. This indicates that the recipient() function
should be called by sendmail, providing the milter with the recipient's
envelope information.
HEADER:
Indicates that the milter defines (overrides) the
header-functionality. This indicates that the header() function
should be called by sendmail for each mail header that is used in the current
mail message.
EOH:
Indicates that the milter defines (overrides) the
end-of-header-functionality. This indicates that the eoh() function
should be called by sendmail once all header lines have been processed.
BODY:
Indicates that the milter defines (overrides) the
body-functionality. This indicates that the body() function
should be called by sendmail, offering the mail-body to the milter.
EOM:
Indicates that the milter defines (overrides) the
end-of-message-functionality. This indicates that the eom() function
should be called by sendmail, once all elements of the e-mail message have
been processed.
ABORT:
Indicates that the milter defines (overrides) the
abort-functionality. The abort() function may be called by sendmail before
eom() is called. It should reclaim all resources used by the message, but
not delete any memory allocated by the milter, as this is close()'s job.
CLOSE:
Indicates that the milter defines (overrides) the
close-functionality. The close() function should delete all (connection
specific) memory allocated by the milter. It may be called `out-of-order',
i.e. even before connect() is called and developers should anticipate this
possibility when crafting their close() code. In particular, it is
incorrect to assume the private context pointer will be something other than
0 in this callback.
UNKNOWN:
Currently not used. Reserved for versions exceeding version 2 of the
sendmail milter API
DATA:
Currently not used. Reserved for versions exceeding version 3 of the
sendmail milter API
ALL_CALLBACKS:
Shortcut to indicate all callback facilities. The CallBack values
are bit-flags. The bit_or operator may be used to combine them, and the
bit_not operator may be used to remove a flag from ALL_CALLBACKS
(e.g., ALL_CALLBACKS && ~ABORT).
enum Flags
This enumeration holds the following values:
NO_FLAGS:
No flags are defined.
ADD_HEADERS:
This flag indicates that the milter is allowed to add headers to the
current e-mail message.
ADD_RECIPIENTS:
This flag indicates that the milter is allowed to add recipients to the
current e-mail message.
CHANGE_BODY:
This flag indicates that the milter is allowed to modify the message's
body contents.
CHANGE_HEADERS:
This flag indicates that the milter is allowed to change headers of
the current e-mail message.
DELETE_RECIPIENTS:
This flag indicates that the milter is allowed to remove recipients
from the current e-mail message.
QUARANTINE:
This flag indicates that the milter is allowed to request sendmail to
quarantine the current e-mail message.
ALL_FLAGS:
Shortcut to indicate all callback facilities. The Flags values
are bit-flags. The bit_or operator may be used to combine them, and the
bit_not operator may be used to remove a flag from ALL_FLAGS
(e.g., ALL_FLAGS && ~QUARANTINE).
Status
This enumeration simplifies the extended SMFIS_ values used by the
C API. These values may be used to return sfsistat values:
ACCEPT:
This value is equal to SMFIS_ACCEPT, indicating that Sendmail
should accept the message. For a connection-oriented callback (see below at
PROTECTED VIRTUAL MEMBER FUNCTIONS), accept this connection without
further filter processing, call close() (see below). For other callbacks:
accept this message without further filtering.
CONTINUE:
This value is equal to SMFIS_CONTINUE, indicating that Sendmail
should continue processing. This is the default for all callback functions
which are not overridden by the class derived from Milter.
DISCARD:
This value is equal to SMFIS_DISCARD, 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.
REJECT:
This value is equal to SMFIS_REJECT, indicating that Sendmail
should reject the mail message. For a connection-oriented callback, reject
this connection; call close(). For a message-oriented callback (except
for eom() or abort(), see below), reject this message. For a
recipient-oriented callback, reject the current recipient (but continue
processing the current message).
TEMPFAIL:
This value is equal to SMFIS_TEMPFAIL, indicating that Sendmail
should return a `temporary unavailable' message to the sender of the mail
message. For a message-oriented callback (except sender(), see below),
fail for this message. For a connection-oriented callback, fail for this
connection and call close(). For a recipient-oriented callback, only fail
for the current recipient and continue message processing.
Return
This enumeration simplifies the extended MI_ values used by the
C API. Most return values used by the Milter class, however, are
bool values. The Return values are:
FAILURE:
This value is equal to MI_FAILURE, indicating that a C-api
function failed to perform its task.
SUCCESS:
This value is equal to MI_SUCCESS, indicating that a C-api
function succeeded in performing its task.
CONSTRUCTORS
The default- and copy constructors are available for derived classes. They
perform no actions.
PUBLIC STATIC MEMBER FUNCTIONS
These functions form the heart of the Milter base-class. They can be
called to initialize, start and stop the Milter.
void initialize(std::string const &name,
Milter &milter,
callback_set callbacks = CONNECT,
flag_set flags = NO_FLAGS):
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 Milter object. Since Milter is an abstract base class
the actual object is always an object of a class derived from Milter. Its
third argument specifies the callbacks to call for this milter. By default the
connect() callback will be called. Note that the close() callback is
not called by default. This is ok, since the Milter object doesn't have to
cleanup `private' data, as is normal with the C API. The last argument
defines flags, specifying the Milter's capabilities.
std::string const &name():
This function returns the milter's name.
bool start():
This member function calls smfi_main(), controlling the milter's
event loop. It returns true if the event-loop is successfully terminated.
void stop():
This member function terminates the milter's event loop, after
finishing all threads. Following this call start() may be called again to
continue the milter.
PROTECTED VIRTUAL MEMBER FUNCTIONS
The remaining functionality of the class Milter is useful only for
Milter-implementations in classes derived from Milter. The following
members can be overridden by derived classes. Note that clone()must
be overridden. Except for clone(), all the members in this sections are
callback functions. I.e., the MTA will call them to process parts of the
mail message. Recipient-, message-, and connection-oriented callbacks are
distinguished.
The recipient-oriented callback (recipient(), see below) may affect
the processing of a single message to a single recipient. Connection-oriented
callbacks (connect(), helo() and close()) 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.
virtual sfsistat abort():
This message-oriented member may be called at any time during message
processing (i.e. between some message-oriented routine and
eom()). abort() reclaim any resources allocated on a per-message basis
(which are not 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. abort() 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
ACCEPT, REJECT, or DISCARD from a message-oriented routine
-x_*.deb: debian package holding the
libraries;
libbobcat1-dev_2.08.01-x_*.deb: debian package holding the
libraries, headers and manual pages;
http://sourceforge.net/projects/bobcat: public archive location;
BOBCAT
Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
COPYRIGHT
This is free software, distributed under the terms of the
GNU General Public License (GPL).
Milter defines an abtract base class interfacing to the sendmail mail
filter (milter) facilities. It defines a C++ interface, based on the
assumption that a single mail filter program does not implement multiple mail
filters. The traditional sendmail C-based Milter API uses a (SMFICTX)
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 C environment these
administratve tasks distract from the main task: the Milter's mail filtering
functionality. The FBB::Milter class hides these administrative tasks from
the programmer, who is then able to concentrate on filtering mail. The main
benefits of Milter are therefore
Basic administration is performed by the Milter class
The class' interface is more C++ like than the raw C
interface offered by the milter API.
Administration, allocation and communicating of connection specific
data is no longer required
It is not normally necessary to use connection-specific data, like a
pointer identifying the connection, anymore when implementing the Milter.
Milter uses current-day design patterns enforcing principles of
reuable software, thus simplifying the construction of the actual Milter.
To activate a milter from the sendmail.mc configuration file, use,
e.g., INPUT_MAIL_FILTER(`name', `S=socket'), where name is the
milter's name, and socket is the name of the socket. See also the
setConnection() member below.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
INHERITS FROM
-
ENUMERATIONS
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:
enum CallBack
This enumeration holds the following values:
CONNECT:
Indicates that the milter defines (overrides) the
connection-functionality. This is the first callback function that can be
called by sendmail.
HELO:
Indicates that the milter defines (overrides) the
helo-functionality. This indicates that the helo() function should be
called by sendmail, providing the milter with information about the connecting
client.
SENDER:
Indicates that the milter defines (overrides) the
sender-functionality. This indicates that the sender() function should be
called by sendmail, providing the milter with the sender's envelope
information.
RECIPIENT:
Indicates that the milter defines (overrides) the
recipient-functionality. This indicates that the recipient() function
should be called by sendmail, providing the milter with the recipient's
envelope information.
HEADER:
Indicates that the milter defines (overrides) the
header-functionality. This indicates that the header() function
should be called by sendmail for each mail header that is used in the current
mail message.
EOH:
Indicates that the milter defines (overrides) the
end-of-header-functionality. This indicates that the eoh() function
should be called by sendmail once all header lines have been processed.
BODY:
Indicates that the milter defines (overrides) the
body-functionality. This indicates that the body() function
should be called by sendmail, offering the mail-body to the milter.
EOM:
Indicates that the milter defines (overrides) the
end-of-message-functionality. This indicates that the eom() function
should be called by sendmail, once all elements of the e-mail message have
been processed.
ABORT:
Indicates that the milter defines (overrides) the
abort-functionality. The abort() function may be called by sendmail before
eom() is called. It should reclaim all resources used by the message, but
not delete any memory allocated by the milter, as this is close()'s job.
CLOSE:
Indicates that the milter defines (overrides) the
close-functionality. The close() function should delete all (connection
specific) memory allocated by the milter. It may be called `out-of-order',
i.e. even before connect() is called and developers should anticipate this
possibility when crafting their close() code. In particular, it is
incorrect to assume the private context pointer will be something other than
0 in this callback.
UNKNOWN:
Currently not used. Reserved for versions exceeding version 2 of the
sendmail milter API
DATA:
Currently not used. Reserved for versions exceeding version 3 of the
sendmail milter API
ALL_CALLBACKS:
Shortcut to indicate all callback facilities. The CallBack values
are bit-flags. The bit_or operator may be used to combine them, and the
bit_not operator may be used to remove a flag from ALL_CALLBACKS
(e.g., ALL_CALLBACKS && ~ABORT).
enum Flags
This enumeration holds the following values:
NO_FLAGS:
No flags are defined.
ADD_HEADERS:
This flag indicates that the milter is allowed to add headers to the
current e-mail message.
ADD_RECIPIENTS:
This flag indicates that the milter is allowed to add recipients to the
current e-mail message.
CHANGE_BODY:
This flag indicates that the milter is allowed to modify the message's
body contents.
CHANGE_HEADERS:
This flag indicates that the milter is allowed to change headers of
the current e-mail message.
DELETE_RECIPIENTS:
This flag indicates that the milter is allowed to remove recipients
from the current e-mail message.
QUARANTINE:
This flag indicates that the milter is allowed to request sendmail to
quarantine the current e-mail message.
ALL_FLAGS:
Shortcut to indicate all callback facilities. The Flags values
are bit-flags. The bit_or operator may be used to combine them, and the
bit_not operator may be used to remove a flag from ALL_FLAGS
(e.g., ALL_FLAGS && ~QUARANTINE).
Status
This enumeration simplifies the extended SMFIS_ values used by the
C API. These values may be used to return sfsistat values:
ACCEPT:
This value is equal to SMFIS_ACCEPT, indicating that Sendmail
should accept the message. For a connection-oriented callback (see below at
PROTECTED VIRTUAL MEMBER FUNCTIONS), accept this connection without
further filter processing, call close() (see below). For other callbacks:
accept this message without further filtering.
CONTINUE:
This value is equal to SMFIS_CONTINUE, indicating that Sendmail
should continue processing. This is the default for all callback functions
which are not overridden by the class derived from Milter.
DISCARD:
This value is equal to SMFIS_DISCARD, 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.
REJECT:
This value is equal to SMFIS_REJECT, indicating that Sendmail
should reject the mail message. For a connection-oriented callback, reject
this connection; call close(). For a message-oriented callback (except
for eom() or abort(), see below), reject this message. For a
recipient-oriented callback, reject the current recipient (but continue
processing the current message).
TEMPFAIL:
This value is equal to SMFIS_TEMPFAIL, indicating that Sendmail
should return a `temporary unavailable' message to the sender of the mail
message. For a message-oriented callback (except sender(), see below),
fail for this message. For a connection-oriented callback, fail for this
connection and call close(). For a recipient-oriented callback, only fail
for the current recipient and continue message processing.
Return
This enumeration simplifies the extended MI_ values used by the
C API. Most return values used by the Milter class, however, are
bool values. The Return values are:
FAILURE:
This value is equal to MI_FAILURE, indicating that a C-api
function failed to perform its task.
SUCCESS:
This value is equal to MI_SUCCESS, indicating that a C-api
function succeeded in performing its task.
CONSTRUCTORS
The default- and copy constructors are available for derived classes. They
perform no actions.
PUBLIC STATIC MEMBER FUNCTIONS
These functions form the heart of the Milter base-class. They can be
called to initialize, start and stop the Milter.
void initialize(std::string const &name,
Milter &milter,
callback_set callbacks = CONNECT,
flag_set flags = NO_FLAGS):
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 Milter object. Since Milter is an abstract base class
the actual object is always an object of a class derived from Milter. Its
third argument specifies the callbacks to call for this milter. By default the
connect() callback will be called. Note that the close() callback is
not called by default. This is ok, since the Milter object doesn't have to
cleanup `private' data, as is normal with the C API. The last argument
defines flags, specifying the Milter's capabilities.
std::string const &name():
This function returns the milter's name.
bool start():
This member function calls smfi_main(), controlling the milter's
event loop. It returns true if the event-loop is successfully terminated.
void stop():
This member function terminates the milter's event loop, after
finishing all threads. Following this call start() may be called again to
continue the milter.
PROTECTED VIRTUAL MEMBER FUNCTIONS
The remaining functionality of the class Milter is useful only for
Milter-implementations in classes derived from Milter. The following
members can be overridden by derived classes. Note that clone()must
be overridden. Except for clone(), all the members in this sections are
callback functions. I.e., the MTA will call them to process parts of the
mail message. Recipient-, message-, and connection-oriented callbacks are
distinguished.
The recipient-oriented callback (recipient(), see below) may affect
the processing of a single message to a single recipient. Connection-oriented
callbacks (connect(), helo() and close()) 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.
virtual sfsistat abort():
This message-oriented member may be called at any time during message
processing (i.e. between some message-oriented routine and
eom()). abort() reclaim any resources allocated on a per-message basis
(which are not 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. abort() 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
ACCEPT, REJECT, or DISCARD from a message-oriented routine
-x_*.deb: debian package holding the
libraries;
libbobcat1-dev_2.08.01-x_*.deb: debian package holding the
libraries, headers and manual pages;
http://sourceforge.net/projects/bobcat: public archive location;
BOBCAT
Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
COPYRIGHT
This is free software, distributed under the terms of the
GNU General Public License (GPL).