Callback functions

Edit online

The sendmail filter must implement one or more of the callback functions, which are registered through smfi_register function.

Table 1. Call back functions
Item	Description
xxfi_connect	The xxfi_connect function is called once at the start of each SMTP connection. The function returns SMFIS_CONTINUE value.
xxfi_hello	The xxfi_hello function is called whenever the client sends a HELO/EHLO command.
xxfi_envfrom	The xxfi_envfrom function is called at the beginning of a message.
xxfi_envrcpt	The xxfi_envrcpt function is called for each recipient.
xxfi_data	The xxfi_data function handles the DATA command.
xxfi_unknown	The xxfi_unknown function handles unknown simple mail transfer protocol (SMTP) commands.
xxfi_header	The xxfi_header function handles a message header.
xxfi_eoh	The xxfi_eoh function handles the message headers.
xxfi_body	The xxfi_body function handles a chunk of a messages body.
xxfi_eom	The xxfi_eom function handles the end of the message.
xxfi_abort	The xxfi_abort function handles the messages that are aborted.
xxfi_close	The xxfi_close function is called to close the current connection.
xxfi_negotiate	The xxfi_negotiate function is called at the start of SMTP connection.

The callback functions must return proper value. If callback functions return any other value than the defined value, it constitutes an error, and the sendmail command terminates the connection to the filter.

The Milter parameter distinguishes between recipient-, message-, and connection-oriented routines:

The recipient-oriented callback functions affect the processing of a single message recipient.
The message-oriented callback functions affect a single message.
The connection-oriented callback functions affect an entire connection (during which multiple messages can be delivered to multiple sets of recipients).
The xxfi_envrcpt function is recipient-oriented. The xxfi_conect, xxfi_hello and xxfi_close functions are connection-oriented. All other callback functions are message-oriented.

Table 2. Callback functions
Item	Description
SMFIS_CONTINUE	Continue processing the current connection, message, or recipient.
SMFIS_REJECT	For a connection-oriented routine, reject this connection; call xxfi_close. For a message-oriented routine (except for xxfi_eom function, or xxfi_abort function), reject this message. For a recipient-oriented routine, reject the current recipient (but continue processing the current message).
SMFIS_DISCARD	For a message- or recipient-oriented routine, accept this message, but discard it. SMFIS_DISCARD must not be returned by a connection-oriented routine.
SMFIS_ACCEPT	For a connection-oriented routine, accept this connection without further filter processing; call xxfi_close function. For a message- or recipient- oriented routine, accept this message without further filtering.
SMFIS_TEMPFAIL	Return a temporary failure, that is, the corresponding simple mail transfer protocol (SMTP) command returns `4xx` status code. For a message-oriented routine (except for xxfi_envfrom function), fail for this message. For a connection-oriented routine, fail for this connection; call xxfi_close function. For a recipient-oriented routine, fail only for the current recipient; continue processing the message.
SMFIS_SKIP	Skip further callbacks of the same type in this transaction. Currently, this return value is only allowed in xxfi_body function. The return value can be used if a milter parameter has received sufficient body chunks to make a decision. But if the return value still wants to invoke the message modification functions that are only allowed to be called from xxfi_eom function. Note: The milter parameter must negotiate this behavior with the mail transfer agent (MTA). The milter parameter checks whether the protocol action SMFIP_SKIP is available. If the protocol action SMFIP_SKIP is available, the milter parameter must request it.
SMFIS_NOREPLY	Do not send a reply to the MTA. The milter parameter must negotiate this behavior with the MTA. The milter parameter must check whether the appropriate protocol action SMFIP_NR_* is available. If the protocol action SMFIP_NR_* is available, the milter parameter must request it. If you set the SMFIP_NR_* protocol action for a callback, that callback must always reply with SMFIS_NOREPLY. Using any other reply code is a violation of the application programming interface (API). If in some cases your callback can return another value (due to some resource shortages), you must not set SMFIP_NR_* and you must use SMFIS_CONTINUE as the default return code. Alternatively, you can try to delay reporting the problem to a later callback for which SMFIP_NR_* is not set.