api.html revision 168515
1168515Sgshapiro<HTML> 2168515Sgshapiro<HEAD><TITLE>Milter API</TITLE></HEAD> 3168515Sgshapiro<BODY> 4132943Sgshapiro<!-- 5168515Sgshapiro$Id: api.html,v 1.35 2006/11/30 23:09:23 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 8390792Sgshapirothe operation. 8490792Sgshapiro 85168515Sgshapiro<P> 8690792SgshapiroA filter must have set the appropriate flag (listed below) in the 87168515Sgshapirodescription passed to <A HREF="smfi_register.html">smfi_register</A> 8890792Sgshapiroto call any message modification function. Failure to do so will 8990792Sgshapirocause the MTA to treat a call to the function as a failure of the 9090792Sgshapirofilter, terminating its connection. 9190792Sgshapiro 92168515Sgshapiro<P> 9390792SgshapiroNote that the status returned indicates only whether or not the 9490792Sgshapirofilter's message was successfully sent to the MTA, not whether or not 95168515Sgshapirothe MTA performed the requested operation. For example, 96168515Sgshapiro<A HREF="smfi_addheader.html">smfi_addheader</A>, when called with an 9790792Sgshapiroillegal header name, will return MI_SUCCESS even though the MTA may 9890792Sgshapirolater refuse to add the illegal header. 99168515Sgshapiro<P> 100168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH><TH>SMFIF_* flag</TR> 101168515Sgshapiro<TR><TD><A HREF="smfi_addheader.html">smfi_addheader</A></TD><TD>Add a header to 102168515Sgshapirothe message.</TD><TD>SMFIF_ADDHDRS</TD></TR> 10390792Sgshapiro 104168515Sgshapiro<TR><TD><A HREF="smfi_chgheader.html">smfi_chgheader</A></TD><TD>Change or delete a header.</TD><TD>SMFIF_CHGHDRS</TD></TR> 10590792Sgshapiro 106168515Sgshapiro<TR><TD><A HREF="smfi_insheader.html">smfi_insheader</A></TD><TD>Insert a 107168515Sgshapiroheader into the message.</TD><TD>SMFIF_ADDHDRS</TD></TR> 108132943Sgshapiro 109168515Sgshapiro<TR><TD><A HREF="smfi_chgfrom.html">smfi_chgfrom</A></TD><TD>Change the 110168515Sgshapiroenvelope sender address.</TD><TD>SMFIF_CHGFROM</TD></TR> 11190792Sgshapiro 112168515Sgshapiro<TR><TD><A HREF="smfi_addrcpt.html">smfi_addrcpt</A></TD><TD>Add a recipient to 113168515Sgshapirothe envelope.</TD><TD>SMFIF_ADDRCPT</TD></TR> 11490792Sgshapiro 115168515Sgshapiro<TR><TD><A HREF="smfi_addrcpt_par.html">smfi_addrcpt_par</A></TD><TD>Add 116168515Sgshapiroa recipient including ESMTP parameter to the envelope. 117168515Sgshapiro</TD><TD>SMFIF_ADDRCPT_PAR</TD></TR> 11890792Sgshapiro 119168515Sgshapiro<TR><TD><A HREF="smfi_delrcpt.html">smfi_delrcpt</A></TD><TD>Delete a recipient 120168515Sgshapirofrom the envelope.</TD><TD>SMFIF_DELRCPT</TD></TR> 12190792Sgshapiro 122168515Sgshapiro<TR><TD><A HREF="smfi_replacebody.html">smfi_replacebody</A></TD><TD>Replace the 123168515Sgshapirobody of the message.</TD><TD>SMFIF_CHGBODY</TD></TR> 12490792Sgshapiro 125168515Sgshapiro</TABLE> 126168515Sgshapiro 127168515Sgshapiro<H2>Other Message Handling Functions</H2> 128168515Sgshapiro 129132943SgshapiroThe following functions provide special case handling instructions for 130132943Sgshapiromilter or the MTA, without altering the content or status of the message. 131168515Sgshapiro<EM>They too may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>. 132132943SgshapiroAll of these functions may invoke additional communication with the MTA. 133132943SgshapiroThey will return either MI_SUCCESS or MI_FAILURE to indicate the status of 134132943Sgshapirothe operation. 135132943Sgshapiro 136168515Sgshapiro<P> 137132943SgshapiroNote that the status returned indicates only whether or not the 138132943Sgshapirofilter's message was successfully sent to the MTA, not whether or not 139132943Sgshapirothe MTA performed the requested operation. 140132943Sgshapiro 141168515Sgshapiro<P> 142168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 143168515Sgshapiro<TR><TD><A HREF="smfi_progress.html">smfi_progress</A></TD><TD>Report operation in progress.</TD></TR> 144132943Sgshapiro 145168515Sgshapiro<TR><TD><A HREF="smfi_quarantine.html">smfi_quarantine</A></TD><TD>Quarantine a message.</TD></TR> 146132943Sgshapiro 147168515Sgshapiro</TABLE> 148132943Sgshapiro 149168515Sgshapiro<H2><A NAME="Callbacks">Callbacks</A></H2> 150132943Sgshapiro 15190792SgshapiroThe filter should implement one or more of the following callbacks, 152168515Sgshapirowhich are registered via <A HREF="smfi_register.html">smfi_register</A>: 15390792Sgshapiro 154168515Sgshapiro<P> 155168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 15690792Sgshapiro 157168515Sgshapiro<TR><TD><A HREF="xxfi_connect.html">xxfi_connect</A></TD><TD>connection info</TD></TR> 15890792Sgshapiro 159168515Sgshapiro<TR><TD><A HREF="xxfi_helo.html">xxfi_helo</A></TD><TD>SMTP HELO/EHLO command</TD></TR> 16090792Sgshapiro 161168515Sgshapiro<TR><TD><A HREF="xxfi_envfrom.html">xxfi_envfrom</A></TD><TD>envelope sender</TD></TR> 16290792Sgshapiro 163168515Sgshapiro<TR><TD><A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A></TD><TD>envelope recipient</TD></TR> 16490792Sgshapiro 165168515Sgshapiro<TR><TD><A HREF="xxfi_data.html">xxfi_data</A></TD><TD>DATA command</TD></TR> 16690792Sgshapiro 167168515Sgshapiro<TR><TD><A HREF="xxfi_unknown.html">xxfi_unknown</A></TD><TD>Unknown SMTP command</TD></TR> 16890792Sgshapiro 169168515Sgshapiro<TR><TD><A HREF="xxfi_header.html">xxfi_header</A></TD><TD>header</TD></TR> 17090792Sgshapiro 171168515Sgshapiro<TR><TD><A HREF="xxfi_eoh.html">xxfi_eoh</A></TD><TD>end of header</TD></TR> 17290792Sgshapiro 173168515Sgshapiro<TR><TD><A HREF="xxfi_body.html">xxfi_body</A></TD><TD>body block</TD></TR> 17490792Sgshapiro 175168515Sgshapiro<TR><TD><A HREF="xxfi_eom.html">xxfi_eom</A></TD><TD>end of message</TD></TR> 17690792Sgshapiro 177168515Sgshapiro<TR><TD><A HREF="xxfi_abort.html">xxfi_abort</A></TD><TD>message aborted</TD></TR> 178168515Sgshapiro 179168515Sgshapiro<TR><TD><A HREF="xxfi_close.html">xxfi_close</A></TD><TD>connection cleanup</TD></TR> 180168515Sgshapiro 181168515Sgshapiro<TR><TD><A HREF="xxfi_negotiate.html">xxfi_negotiate</A></TD><TD>option negotiattion</TD></TR> 182168515Sgshapiro 183168515Sgshapiro</TABLE> 184168515Sgshapiro 185168515Sgshapiro<P> 18690792SgshapiroThe above callbacks should all return one of the following return values, 18790792Sgshapirohaving the indicated meanings. Any return other than one of the below 18890792Sgshapirovalues constitutes an error, and will cause sendmail to terminate its 18990792Sgshapiroconnection to the offending filter. 19090792Sgshapiro 191168515Sgshapiro<P><A NAME="conn-spec">Milter</A> distinguishes between recipient-, 19290792Sgshapiromessage-, and connection-oriented routines. Recipient-oriented 19390792Sgshapirocallbacks may affect the processing of a single message recipient; 19490792Sgshapiromessage-oriented callbacks, a single message; connection-oriented 19590792Sgshapirocallbacks, an entire connection (during which multiple messages may be 19690792Sgshapirodelivered to multiple sets of recipients). 197168515Sgshapiro<A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A> is recipient-oriented. 198168515Sgshapiro<A HREF="xxfi_connect.html">xxfi_connect</A>, 199168515Sgshapiro<A HREF="xxfi_helo.html">xxfi_helo</A> and 200168515Sgshapiro<A HREF="xxfi_close.html">xxfi_close</A> are connection-oriented. All 20190792Sgshapiroother callbacks are message-oriented. 20290792Sgshapiro 203168515Sgshapiro<P> 204168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2> 205168515Sgshapiro <TR BGCOLOR="#dddddd"><TH>Return value</TH><TH>Description</TH></TR> 206168515Sgshapiro <TR VALIGN="TOP"> 207168515Sgshapiro <TD>SMFIS_CONTINUE</TD> 208168515Sgshapiro <TD>Continue processing the current connection, message, or recipient. 209168515Sgshapiro </TD> 210168515Sgshapiro </TR> 211168515Sgshapiro <TR VALIGN="TOP"> 212168515Sgshapiro <TD>SMFIS_REJECT</TD> 213168515Sgshapiro <TD>For a connection-oriented routine, reject this connection; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR> 21490792Sgshapiro For a message-oriented routine (except 215168515Sgshapiro <A HREF="xxfi_eom.html">xxfi_eom</A> or 216168515Sgshapiro <A HREF="xxfi_abort.html">xxfi_abort</A>), reject this message.<BR> 21790792Sgshapiro For a recipient-oriented routine, reject the current recipient (but continue processing the current message). 218168515Sgshapiro </TD> 219168515Sgshapiro </TR> 220168515Sgshapiro <TR valign="top"> 221168515Sgshapiro <TD>SMFIS_DISCARD</TD> 222168515Sgshapiro <TD>For a message- or recipient-oriented routine, accept this message, but silently discard it.<BR> 22390792Sgshapiro SMFIS_DISCARD should not be returned by a connection-oriented routine. 224168515Sgshapiro </TD> 225168515Sgshapiro </TR> 226168515Sgshapiro <TR valign="top"> 227168515Sgshapiro <TD>SMFIS_ACCEPT</TD> 228168515Sgshapiro <TD>For a connection-oriented routine, accept this connection without further filter processing; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR> 229168515Sgshapiro For a message- or recipient-oriented routine, accept this message without further filtering.<BR> 230168515Sgshapiro </TD> 231168515Sgshapiro </TR> 232168515Sgshapiro <TR valign="top"> 233168515Sgshapiro <TD>SMFIS_TEMPFAIL</TD> 234168515Sgshapiro <TD>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code. 235168515Sgshapiro For a message-oriented routine (except <A HREF="xxfi_envfrom.html">xxfi_envfrom</A>), fail for this message. <BR> 236168515Sgshapiro For a connection-oriented routine, fail for this connection; call <A HREF="xxfi_close.html">xxfi_close</A>. <BR> 23790792Sgshapiro For a recipient-oriented routine, only fail for the current recipient; continue message processing. 238168515Sgshapiro </TD> 239168515Sgshapiro </TR> 24090792Sgshapiro 241168515Sgshapiro <TR valign="top"> 242168515Sgshapiro <TD><A NAME="SMFIS_SKIP">SMFIS_SKIP</A></TD> 243168515Sgshapiro <TD>Skip further callbacks of the same type in this transaction. 244168515Sgshapiro Currently this return value is only allowed in 245168515Sgshapiro <A HREF="xxfi_body.html">xxfi_body()</A>. 246168515Sgshapiro It can be used if a milter has received sufficiently many 247168515Sgshapiro body chunks to make a decision, but still wants to invoke 248168515Sgshapiro message modification functions that are only allowed to be called from 249168515Sgshapiro <A HREF="xxfi_eom.html">xxfi_eom()</A>. 250168515Sgshapiro Note: the milter <EM>must</EM> 251168515Sgshapiro <A HREF="xxfi_negotiate.html">negotiate</A> 252168515Sgshapiro this behavior with the MTA, i.e., it must check whether 253168515Sgshapiro the protocol action 254168515Sgshapiro <A HREF="xxfi_negotiate.html#SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A> 255168515Sgshapiro is available and if so, the milter must request it. 256168515Sgshapiro </TD> 257168515Sgshapiro </TR> 258168515Sgshapiro 259168515Sgshapiro <TR valign="top"> 260168515Sgshapiro <TD><A NAME="SMFIS_NOREPLY">SMFIS_NOREPLY</A></TD> 261168515Sgshapiro <TD>Do not send a reply back to the MTA. 262168515Sgshapiro The milter <EM>must</EM> 263168515Sgshapiro <A HREF="xxfi_negotiate.html">negotiate</A> 264168515Sgshapiro this behavior with the MTA, i.e., it must check whether 265168515Sgshapiro the appropriate protocol action 266168515Sgshapiro <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 267168515Sgshapiro is available and if so, the milter must request it. 268168515Sgshapiro If you set the 269168515Sgshapiro <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 270168515Sgshapiro protocol action for a callback, that callback <EM>must</EM> 271168515Sgshapiro always reply with 272168515Sgshapiro SMFIS_NOREPLY. 273168515Sgshapiro Using any other reply code is a violation of the API. 274168515Sgshapiro If in some cases your callback may return another value 275168515Sgshapiro (e.g., due to some resource shortages), then you 276168515Sgshapiro <EM>must not</EM> set 277168515Sgshapiro <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 278168515Sgshapiro and you must use 279168515Sgshapiro SMFIS_CONTINUE as the default return code. 280168515Sgshapiro (Alternatively you can try to delay reporting the problem to 281168515Sgshapiro a later callback for which 282168515Sgshapiro <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 283168515Sgshapiro is not set.) 284168515Sgshapiro </TD> 285168515Sgshapiro </TR> 286168515Sgshapiro 287168515Sgshapiro</TABLE> 288168515Sgshapiro 289168515Sgshapiro<H2><A NAME="Miscellaneous">Miscellaneous</A></H2> 290168515Sgshapiro 291168515Sgshapiro<P> 292168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 293168515Sgshapiro 294168515Sgshapiro<TR><TD><A HREF="smfi_version.html">smfi_version</A></TD><TD>libmilter (runtime) version info</TD></TR> 295168515Sgshapiro 296168515Sgshapiro<TR><TD><A HREF="smfi_setsymlist.html">smfi_setsymlist</A></TD><TD> 297168515SgshapiroSet the list of macros that the milter wants to receive from the MTA 298168515Sgshapirofor a protocol stage. 299168515Sgshapiro</TD></TR> 300168515Sgshapiro 301168515Sgshapiro</TABLE> 302168515Sgshapiro 303168515Sgshapiro<P> 304168515Sgshapiro<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Constant</TH><TH>Description</TH></TR> 305168515Sgshapiro 306168515Sgshapiro<TR><TD><A HREF="smfi_version.html">SMFI_VERSION</A></TD><TD>libmilter (compile time) version info</TD></TR> 307168515Sgshapiro 308168515Sgshapiro</TABLE> 309168515Sgshapiro 310168515Sgshapiro 311168515Sgshapiro<HR SIZE="1"> 312168515Sgshapiro<FONT SIZE="-1"> 313168515SgshapiroCopyright (c) 2000, 2003, 2006 Sendmail, Inc. and its suppliers. 31490792SgshapiroAll rights reserved. 315168515Sgshapiro<BR> 31690792SgshapiroBy using this file, you agree to the terms and conditions set 317112810Sgshapiroforth in the LICENSE. 318168515Sgshapiro</FONT> 319168515Sgshapiro</BODY> 320168515Sgshapiro</HTML> 321