Library Control Functions
Before handing control to libmilter (by calling smfi_main), a filter may call the following functions to set libmilter parameters. In particular, the filter must call smfi_register to register its callbacks. Each function will return either MI_SUCCESS or MI_FAILURE to indicate the status of the operation.
None of these functions communicate with the MTA. All alter the library's state, some of which is communicated to the MTA inside smfi_main.
|smfi_opensocket||Try to create the interface socket.|
|smfi_register||Register a filter.|
|smfi_setconn||Specify socket to use.|
|smfi_setbacklog||Define the incoming
|smfi_setdbg||Set the milter library debugging (tracing) level.|
|smfi_stop||Cause an orderly shutdown.|
|smfi_main||Hand control to libmilter.|
Data Access Functions
The following functions may be called from within the filter-defined callbacks to access information about the current connection or message.
|smfi_getsymval||Return the value of a symbol.|
|smfi_getpriv||Get the private data pointer.|
|smfi_setpriv||Set the private data pointer.|
|smfi_setreply||Set the specific reply code to be used.|
|smfi_setmlreply||Set the specific multi-line reply to be used.|
Message Modification Functions
The following functions change a message's contents and attributes. They may only be called in xxfi_eom. All of these functions may invoke additional communication with the MTA. They will return either MI_SUCCESS or MI_FAILURE to indicate the status of the operation.
A filter must have set the appropriate flag (listed below) in the description passed to smfi_register to call any message modification function. Failure to do so will cause the MTA to treat a call to the function as a failure of the filter, terminating its connection.
Note that the status returned indicates only whether or not the filter's message was successfully sent to the MTA, not whether or not the MTA performed the requested operation. For example, smfi_addheader, when called with an illegal header name, will return MI_SUCCESS even though the MTA may later refuse to add the illegal header.
|smfi_addheader||Add a header to the message.||SMFIF_ADDHDRS|
|smfi_chgheader||Change or delete a header.||SMFIF_CHGHDRS|
|smfi_insheader||Insert a header into the message.||SMFIF_ADDHDRS|
|smfi_chgfrom||Change the envelope sender address.||SMFIF_CHGFROM|
|smfi_addrcpt||Add a recipient to the envelope.||SMFIF_ADDRCPT|
|smfi_addrcpt_par||Add a recipient including ESMTP parameter to the envelope.||SMFIF_ADDRCPT_PAR|
|smfi_delrcpt||Delete a recipient from the envelope.||SMFIF_DELRCPT|
|smfi_replacebody||Replace the body of the message.||SMFIF_CHGBODY|
Other Message Handling Functions
The following functions provide special case handling instructions for milter or the MTA, without altering the content or status of the message. They too may only be called in xxfi_eom. All of these functions may invoke additional communication with the MTA. They will return either MI_SUCCESS or MI_FAILURE to indicate the status of the operation.
Note that the status returned indicates only whether or not the filter's message was successfully sent to the MTA, not whether or not the MTA performed the requested operation.
|smfi_progress||Report operation in progress.|
|smfi_quarantine||Quarantine a message.|
The filter should implement one or more of the following callbacks, which are registered via smfi_register:
|xxfi_helo||SMTP HELO/EHLO command|
|xxfi_unknown||Unknown SMTP command|
|xxfi_eoh||end of header|
|xxfi_eom||end of message|
The above callbacks should all return one of the following return values, having the indicated meanings. Any return other than one of the below values constitutes an error, and will cause sendmail to terminate its connection to the offending filter.
Milter distinguishes between recipient-, message-, and connection-oriented routines. Recipient-oriented callbacks may affect the processing of a single message recipient; message-oriented callbacks, a single message; connection-oriented callbacks, an entire connection (during which multiple messages may be delivered to multiple sets of recipients). xxfi_envrcpt is recipient-oriented. xxfi_connect, xxfi_helo and xxfi_close are connection-oriented. All other callbacks are message-oriented.