1168515Sgshapiro<HTML> 2168515Sgshapiro<HEAD><TITLE>Milter API</TITLE></HEAD> 3168515Sgshapiro<BODY> 4132943Sgshapiro<!-- 5244833Sgshapiro$Id: api.html,v 1.38 2012/03/29 03:18:37 ca Exp $ 6132943Sgshapiro--> 7168515Sgshapiro<H1>Milter API</H1> 890792Sgshapiro 9168515Sgshapiro<H2>Contents</H2> 10168515Sgshapiro<UL> 11168515Sgshapiro <LI><A HREF="#LibraryControlFunctions">Library Control Functions</A> 12168515Sgshapiro <LI><A HREF="#DataAccessFunctions">Data Access Functions</A> 13168515Sgshapiro <LI><A HREF="#MessageModificationFunctions">Message Modification Functions</A> 14168515Sgshapiro <LI><A HREF="#Callbacks">Callbacks</A> 15168515Sgshapiro <LI><A HREF="#Miscellaneous">Miscellaneous</A> 16168515Sgshapiro</UL> 1790792Sgshapiro 18168515Sgshapiro<H2><A NAME="LibraryControlFunctions">Library Control Functions</A></H2> 1990792Sgshapiro 20168515SgshapiroBefore handing control to libmilter (by calling 21168515Sgshapiro<A HREF="smfi_main.html">smfi_main</A>), a filter may call the following 22168515Sgshapirofunctions to set libmilter parameters. 23168515SgshapiroIn particular, the filter must call 24168515Sgshapiro<A HREF="smfi_register.html">smfi_register</A> to register its callbacks. 25168515SgshapiroEach function will return either MI_SUCCESS or MI_FAILURE to 2690792Sgshapiroindicate the status of the operation. 27168515Sgshapiro 28168515Sgshapiro<P> 2990792SgshapiroNone of these functions communicate with the MTA. All alter the 30168515Sgshapirolibrary's state, some of which is communicated to the MTA inside 31168515Sgshapiro<A HREF="smfi_main.html">smfi_main</A>. 3290792Sgshapiro 33168515Sgshapiro<P> 34168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 35132943Sgshapiro 36168515Sgshapiro<TR><TD><A HREF="smfi_opensocket.html">smfi_opensocket</A></TD><TD>Try to create the interface socket.</TD></TR> 3790792Sgshapiro 38168515Sgshapiro<TR><TD><A HREF="smfi_register.html">smfi_register</A></TD><TD>Register a filter.</TD></TR> 3990792Sgshapiro 40168515Sgshapiro<TR><TD><A HREF="smfi_setconn.html">smfi_setconn</A></TD><TD>Specify socket to use.</TD></TR> 4190792Sgshapiro 42168515Sgshapiro<TR><TD><A HREF="smfi_settimeout.html">smfi_settimeout</A></TD><TD>Set timeout.</TD></TR> 43132943Sgshapiro 44168515Sgshapiro<TR><TD><A HREF="smfi_setbacklog.html">smfi_setbacklog</A></TD><TD>Define the incoming <CODE>listen(2)</CODE> queue size.</TD></TR> 45132943Sgshapiro 46168515Sgshapiro<TR><TD><A HREF="smfi_setdbg.html">smfi_setdbg</A></TD><TD>Set the milter library debugging (tracing) level.</TD></TR> 47132943Sgshapiro 48168515Sgshapiro<TR><TD><A HREF="smfi_stop.html">smfi_stop</A></TD><TD>Cause an orderly shutdown.</TD></TR> 4990792Sgshapiro 50168515Sgshapiro<TR><TD><A HREF="smfi_main.html">smfi_main</A></TD><TD>Hand control to libmilter.</TD></TR> 5190792Sgshapiro 52168515Sgshapiro</TABLE> 5390792Sgshapiro 54168515Sgshapiro<H2><A NAME="DataAccessFunctions">Data Access Functions</A></H2> 55168515Sgshapiro 5690792SgshapiroThe following functions may be called from within the filter-defined callbacks 5790792Sgshapiroto access information about the current connection or message. 58168515Sgshapiro<P> 59168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR bgcolor="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 60168515Sgshapiro<TR><TD><A HREF="smfi_getsymval.html">smfi_getsymval</A></TD><TD>Return the value 61168515Sgshapiroof a symbol.</TD></TR> 6290792Sgshapiro 63168515Sgshapiro<TR><TD><A HREF="smfi_getpriv.html">smfi_getpriv</A></TD><TD>Get the private data 64168515Sgshapiropointer.</TD></TR> 6590792Sgshapiro 66168515Sgshapiro<TR><TD><A HREF="smfi_setpriv.html">smfi_setpriv</A></TD><TD>Set the private data 67168515Sgshapiropointer.</TD></TR> 6890792Sgshapiro 69168515Sgshapiro<TR><TD><A HREF="smfi_setreply.html">smfi_setreply</A></TD><TD>Set the specific 70168515Sgshapiroreply code to be used.</TD></TR> 7190792Sgshapiro 72168515Sgshapiro<TR><TD><A HREF="smfi_setmlreply.html">smfi_setmlreply</A></TD><TD>Set the 73168515Sgshapirospecific multi-line reply to be used.</TD></TR> 74132943Sgshapiro 75168515Sgshapiro</TABLE> 7690792Sgshapiro 77168515Sgshapiro<H2><A NAME="MessageModificationFunctions">Message Modification Functions</A></H2> 7890792Sgshapiro 7990792SgshapiroThe following functions change a message's contents and attributes. 80168515Sgshapiro<EM>They may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>. 8190792SgshapiroAll of these functions may invoke additional communication with the MTA. 8290792SgshapiroThey will return either MI_SUCCESS or MI_FAILURE to indicate the status of 83203004Sgshapirothe operation. Message data (senders, recipients, headers, body chunks) 84203004Sgshapiropassed to these functions via parameters is copied and does not need to be 85203004Sgshapiropreserved (i.e., allocated memory can be freed). 8690792Sgshapiro 87168515Sgshapiro<P> 8890792SgshapiroA filter must have set the appropriate flag (listed below) in the 89168515Sgshapirodescription passed to <A HREF="smfi_register.html">smfi_register</A> 9090792Sgshapiroto call any message modification function. Failure to do so will 9190792Sgshapirocause the MTA to treat a call to the function as a failure of the 9290792Sgshapirofilter, terminating its connection. 9390792Sgshapiro 94168515Sgshapiro<P> 9590792SgshapiroNote that the status returned indicates only whether or not the 9690792Sgshapirofilter's message was successfully sent to the MTA, not whether or not 97168515Sgshapirothe MTA performed the requested operation. For example, 98168515Sgshapiro<A HREF="smfi_addheader.html">smfi_addheader</A>, when called with an 9990792Sgshapiroillegal header name, will return MI_SUCCESS even though the MTA may 10090792Sgshapirolater refuse to add the illegal header. 101168515Sgshapiro<P> 102168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH><TH>SMFIF_* flag</TR> 103168515Sgshapiro<TR><TD><A HREF="smfi_addheader.html">smfi_addheader</A></TD><TD>Add a header to 104168515Sgshapirothe message.</TD><TD>SMFIF_ADDHDRS</TD></TR> 10590792Sgshapiro 106168515Sgshapiro<TR><TD><A HREF="smfi_chgheader.html">smfi_chgheader</A></TD><TD>Change or delete a header.</TD><TD>SMFIF_CHGHDRS</TD></TR> 10790792Sgshapiro 108168515Sgshapiro<TR><TD><A HREF="smfi_insheader.html">smfi_insheader</A></TD><TD>Insert a 109168515Sgshapiroheader into the message.</TD><TD>SMFIF_ADDHDRS</TD></TR> 110132943Sgshapiro 111168515Sgshapiro<TR><TD><A HREF="smfi_chgfrom.html">smfi_chgfrom</A></TD><TD>Change the 112168515Sgshapiroenvelope sender address.</TD><TD>SMFIF_CHGFROM</TD></TR> 11390792Sgshapiro 114168515Sgshapiro<TR><TD><A HREF="smfi_addrcpt.html">smfi_addrcpt</A></TD><TD>Add a recipient to 115168515Sgshapirothe envelope.</TD><TD>SMFIF_ADDRCPT</TD></TR> 11690792Sgshapiro 117168515Sgshapiro<TR><TD><A HREF="smfi_addrcpt_par.html">smfi_addrcpt_par</A></TD><TD>Add 118168515Sgshapiroa recipient including ESMTP parameter to the envelope. 119168515Sgshapiro</TD><TD>SMFIF_ADDRCPT_PAR</TD></TR> 12090792Sgshapiro 121168515Sgshapiro<TR><TD><A HREF="smfi_delrcpt.html">smfi_delrcpt</A></TD><TD>Delete a recipient 122168515Sgshapirofrom the envelope.</TD><TD>SMFIF_DELRCPT</TD></TR> 12390792Sgshapiro 124168515Sgshapiro<TR><TD><A HREF="smfi_replacebody.html">smfi_replacebody</A></TD><TD>Replace the 125168515Sgshapirobody of the message.</TD><TD>SMFIF_CHGBODY</TD></TR> 12690792Sgshapiro 127168515Sgshapiro</TABLE> 128168515Sgshapiro 129168515Sgshapiro<H2>Other Message Handling Functions</H2> 130168515Sgshapiro 131132943SgshapiroThe following functions provide special case handling instructions for 132132943Sgshapiromilter or the MTA, without altering the content or status of the message. 133168515Sgshapiro<EM>They too may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>. 134132943SgshapiroAll of these functions may invoke additional communication with the MTA. 135132943SgshapiroThey will return either MI_SUCCESS or MI_FAILURE to indicate the status of 136132943Sgshapirothe operation. 137132943Sgshapiro 138168515Sgshapiro<P> 139132943SgshapiroNote that the status returned indicates only whether or not the 140132943Sgshapirofilter's message was successfully sent to the MTA, not whether or not 141132943Sgshapirothe MTA performed the requested operation. 142132943Sgshapiro 143168515Sgshapiro<P> 144168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 145168515Sgshapiro<TR><TD><A HREF="smfi_progress.html">smfi_progress</A></TD><TD>Report operation in progress.</TD></TR> 146132943Sgshapiro 147168515Sgshapiro<TR><TD><A HREF="smfi_quarantine.html">smfi_quarantine</A></TD><TD>Quarantine a message.</TD></TR> 148132943Sgshapiro 149168515Sgshapiro</TABLE> 150132943Sgshapiro 151168515Sgshapiro<H2><A NAME="Callbacks">Callbacks</A></H2> 152132943Sgshapiro 15390792SgshapiroThe filter should implement one or more of the following callbacks, 154168515Sgshapirowhich are registered via <A HREF="smfi_register.html">smfi_register</A>: 15590792Sgshapiro 156168515Sgshapiro<P> 157168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 15890792Sgshapiro 159168515Sgshapiro<TR><TD><A HREF="xxfi_connect.html">xxfi_connect</A></TD><TD>connection info</TD></TR> 16090792Sgshapiro 161168515Sgshapiro<TR><TD><A HREF="xxfi_helo.html">xxfi_helo</A></TD><TD>SMTP HELO/EHLO command</TD></TR> 16290792Sgshapiro 163168515Sgshapiro<TR><TD><A HREF="xxfi_envfrom.html">xxfi_envfrom</A></TD><TD>envelope sender</TD></TR> 16490792Sgshapiro 165168515Sgshapiro<TR><TD><A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A></TD><TD>envelope recipient</TD></TR> 16690792Sgshapiro 167168515Sgshapiro<TR><TD><A HREF="xxfi_data.html">xxfi_data</A></TD><TD>DATA command</TD></TR> 16890792Sgshapiro 169168515Sgshapiro<TR><TD><A HREF="xxfi_unknown.html">xxfi_unknown</A></TD><TD>Unknown SMTP command</TD></TR> 17090792Sgshapiro 171168515Sgshapiro<TR><TD><A HREF="xxfi_header.html">xxfi_header</A></TD><TD>header</TD></TR> 17290792Sgshapiro 173168515Sgshapiro<TR><TD><A HREF="xxfi_eoh.html">xxfi_eoh</A></TD><TD>end of header</TD></TR> 17490792Sgshapiro 175168515Sgshapiro<TR><TD><A HREF="xxfi_body.html">xxfi_body</A></TD><TD>body block</TD></TR> 17690792Sgshapiro 177168515Sgshapiro<TR><TD><A HREF="xxfi_eom.html">xxfi_eom</A></TD><TD>end of message</TD></TR> 17890792Sgshapiro 179168515Sgshapiro<TR><TD><A HREF="xxfi_abort.html">xxfi_abort</A></TD><TD>message aborted</TD></TR> 180168515Sgshapiro 181168515Sgshapiro<TR><TD><A HREF="xxfi_close.html">xxfi_close</A></TD><TD>connection cleanup</TD></TR> 182168515Sgshapiro 183168515Sgshapiro<TR><TD><A HREF="xxfi_negotiate.html">xxfi_negotiate</A></TD><TD>option negotiattion</TD></TR> 184168515Sgshapiro 185168515Sgshapiro</TABLE> 186168515Sgshapiro 187168515Sgshapiro<P> 18890792SgshapiroThe above callbacks should all return one of the following return values, 18990792Sgshapirohaving the indicated meanings. Any return other than one of the below 19090792Sgshapirovalues constitutes an error, and will cause sendmail to terminate its 19190792Sgshapiroconnection to the offending filter. 19290792Sgshapiro 193168515Sgshapiro<P><A NAME="conn-spec">Milter</A> distinguishes between recipient-, 19490792Sgshapiromessage-, and connection-oriented routines. Recipient-oriented 19590792Sgshapirocallbacks may affect the processing of a single message recipient; 19690792Sgshapiromessage-oriented callbacks, a single message; connection-oriented 19790792Sgshapirocallbacks, an entire connection (during which multiple messages may be 19890792Sgshapirodelivered to multiple sets of recipients). 199168515Sgshapiro<A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A> is recipient-oriented. 200168515Sgshapiro<A HREF="xxfi_connect.html">xxfi_connect</A>, 201168515Sgshapiro<A HREF="xxfi_helo.html">xxfi_helo</A> and 202168515Sgshapiro<A HREF="xxfi_close.html">xxfi_close</A> are connection-oriented. All 20390792Sgshapiroother callbacks are message-oriented. 20490792Sgshapiro 205168515Sgshapiro<P> 206168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2> 207168515Sgshapiro <TR BGCOLOR="#dddddd"><TH>Return value</TH><TH>Description</TH></TR> 208168515Sgshapiro <TR VALIGN="TOP"> 209168515Sgshapiro <TD>SMFIS_CONTINUE</TD> 210168515Sgshapiro <TD>Continue processing the current connection, message, or recipient. 211168515Sgshapiro </TD> 212168515Sgshapiro </TR> 213168515Sgshapiro <TR VALIGN="TOP"> 214168515Sgshapiro <TD>SMFIS_REJECT</TD> 215168515Sgshapiro <TD>For a connection-oriented routine, reject this connection; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR> 21690792Sgshapiro For a message-oriented routine (except 217168515Sgshapiro <A HREF="xxfi_abort.html">xxfi_abort</A>), reject this message.<BR> 21890792Sgshapiro For a recipient-oriented routine, reject the current recipient (but continue processing the current message). 219168515Sgshapiro </TD> 220168515Sgshapiro </TR> 221168515Sgshapiro <TR valign="top"> 222168515Sgshapiro <TD>SMFIS_DISCARD</TD> 223168515Sgshapiro <TD>For a message- or recipient-oriented routine, accept this message, but silently discard it.<BR> 22490792Sgshapiro SMFIS_DISCARD should not be returned by a connection-oriented routine. 225168515Sgshapiro </TD> 226168515Sgshapiro </TR> 227168515Sgshapiro <TR valign="top"> 228168515Sgshapiro <TD>SMFIS_ACCEPT</TD> 229168515Sgshapiro <TD>For a connection-oriented routine, accept this connection without further filter processing; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR> 230168515Sgshapiro For a message- or recipient-oriented routine, accept this message without further filtering.<BR> 231168515Sgshapiro </TD> 232168515Sgshapiro </TR> 233168515Sgshapiro <TR valign="top"> 234168515Sgshapiro <TD>SMFIS_TEMPFAIL</TD> 235168515Sgshapiro <TD>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code. 236168515Sgshapiro For a message-oriented routine (except <A HREF="xxfi_envfrom.html">xxfi_envfrom</A>), fail for this message. <BR> 237168515Sgshapiro For a connection-oriented routine, fail for this connection; call <A HREF="xxfi_close.html">xxfi_close</A>. <BR> 23890792Sgshapiro For a recipient-oriented routine, only fail for the current recipient; continue message processing. 239168515Sgshapiro </TD> 240168515Sgshapiro </TR> 24190792Sgshapiro 242168515Sgshapiro <TR valign="top"> 243168515Sgshapiro <TD><A NAME="SMFIS_SKIP">SMFIS_SKIP</A></TD> 244168515Sgshapiro <TD>Skip further callbacks of the same type in this transaction. 245168515Sgshapiro Currently this return value is only allowed in 246168515Sgshapiro <A HREF="xxfi_body.html">xxfi_body()</A>. 247168515Sgshapiro It can be used if a milter has received sufficiently many 248168515Sgshapiro body chunks to make a decision, but still wants to invoke 249168515Sgshapiro message modification functions that are only allowed to be called from 250168515Sgshapiro <A HREF="xxfi_eom.html">xxfi_eom()</A>. 251168515Sgshapiro Note: the milter <EM>must</EM> 252168515Sgshapiro <A HREF="xxfi_negotiate.html">negotiate</A> 253168515Sgshapiro this behavior with the MTA, i.e., it must check whether 254168515Sgshapiro the protocol action 255168515Sgshapiro <A HREF="xxfi_negotiate.html#SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A> 256168515Sgshapiro is available and if so, the milter must request it. 257168515Sgshapiro </TD> 258168515Sgshapiro </TR> 259168515Sgshapiro 260168515Sgshapiro <TR valign="top"> 261168515Sgshapiro <TD><A NAME="SMFIS_NOREPLY">SMFIS_NOREPLY</A></TD> 262168515Sgshapiro <TD>Do not send a reply back to the MTA. 263168515Sgshapiro The milter <EM>must</EM> 264168515Sgshapiro <A HREF="xxfi_negotiate.html">negotiate</A> 265168515Sgshapiro this behavior with the MTA, i.e., it must check whether 266168515Sgshapiro the appropriate protocol action 267168515Sgshapiro <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 268168515Sgshapiro is available and if so, the milter must request it. 269168515Sgshapiro If you set the 270168515Sgshapiro <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 271168515Sgshapiro protocol action for a callback, that callback <EM>must</EM> 272168515Sgshapiro always reply with 273168515Sgshapiro SMFIS_NOREPLY. 274168515Sgshapiro Using any other reply code is a violation of the API. 275168515Sgshapiro If in some cases your callback may return another value 276168515Sgshapiro (e.g., due to some resource shortages), then you 277168515Sgshapiro <EM>must not</EM> set 278168515Sgshapiro <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 279168515Sgshapiro and you must use 280168515Sgshapiro SMFIS_CONTINUE as the default return code. 281168515Sgshapiro (Alternatively you can try to delay reporting the problem to 282168515Sgshapiro a later callback for which 283168515Sgshapiro <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 284168515Sgshapiro is not set.) 285168515Sgshapiro </TD> 286168515Sgshapiro </TR> 287168515Sgshapiro 288168515Sgshapiro</TABLE> 289168515Sgshapiro 290168515Sgshapiro<H2><A NAME="Miscellaneous">Miscellaneous</A></H2> 291168515Sgshapiro 292168515Sgshapiro<P> 293168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 294168515Sgshapiro 295168515Sgshapiro<TR><TD><A HREF="smfi_version.html">smfi_version</A></TD><TD>libmilter (runtime) version info</TD></TR> 296168515Sgshapiro 297168515Sgshapiro<TR><TD><A HREF="smfi_setsymlist.html">smfi_setsymlist</A></TD><TD> 298168515SgshapiroSet the list of macros that the milter wants to receive from the MTA 299168515Sgshapirofor a protocol stage. 300168515Sgshapiro</TD></TR> 301168515Sgshapiro 302168515Sgshapiro</TABLE> 303168515Sgshapiro 304168515Sgshapiro<P> 305168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Constant</TH><TH>Description</TH></TR> 306168515Sgshapiro 307168515Sgshapiro<TR><TD><A HREF="smfi_version.html">SMFI_VERSION</A></TD><TD>libmilter (compile time) version info</TD></TR> 308168515Sgshapiro 309168515Sgshapiro</TABLE> 310168515Sgshapiro 311168515Sgshapiro 312168515Sgshapiro<HR SIZE="1"> 313168515Sgshapiro<FONT SIZE="-1"> 314203004SgshapiroCopyright (c) 2000, 2003, 2006, 2009 Sendmail, Inc. and its suppliers. 31590792SgshapiroAll rights reserved. 316168515Sgshapiro<BR> 31790792SgshapiroBy using this file, you agree to the terms and conditions set 318112810Sgshapiroforth in the LICENSE. 319168515Sgshapiro</FONT> 320168515Sgshapiro</BODY> 321168515Sgshapiro</HTML> 322