Merge from vendor branch BZIP:
[dragonfly.git] / contrib / sendmail-8.13.4 / include / libmilter / mfapi.h
1 /*
2  * Copyright (c) 1999-2004 Sendmail, Inc. and its suppliers.
3  *      All rights reserved.
4  *
5  * By using this file, you agree to the terms and conditions set
6  * forth in the LICENSE file which can be found at the top level of
7  * the sendmail distribution.
8  *
9  *
10  *      $Id: mfapi.h,v 8.60 2004/08/20 21:24:14 ca Exp $
11  */
12
13 /*
14 **  MFAPI.H -- Global definitions for mail filter library and mail filters.
15 */
16
17 #ifndef _LIBMILTER_MFAPI_H
18 # define _LIBMILTER_MFAPI_H     1
19
20 #ifndef SMFI_VERSION
21 # define SMFI_VERSION   2               /* version number */
22 #endif /* ! SMFI_VERSION */
23
24 # include <sys/types.h>
25 # include <sys/socket.h>
26
27 #include "libmilter/mfdef.h"
28
29 # define LIBMILTER_API          extern
30
31
32 /* Only need to export C interface if used by C++ source code */
33 #ifdef __cplusplus
34 extern "C" {
35 #endif /* __cplusplus */
36
37 #ifndef _SOCK_ADDR
38 # define _SOCK_ADDR     struct sockaddr
39 #endif /* ! _SOCK_ADDR */
40
41 /*
42 **  libmilter functions return one of the following to indicate
43 **  success/failure:
44 */
45
46 #define MI_SUCCESS      0
47 #define MI_FAILURE      (-1)
48
49 /* "forward" declarations */
50 typedef struct smfi_str SMFICTX;
51 typedef struct smfi_str *SMFICTX_PTR;
52
53 typedef struct smfiDesc smfiDesc_str;
54 typedef struct smfiDesc *smfiDesc_ptr;
55
56 /*
57 **  Type which callbacks should return to indicate message status.
58 **  This may take on one of the SMFIS_* values listed below.
59 */
60
61 typedef int     sfsistat;
62
63 #if defined(__linux__) && defined(__GNUC__) && defined(__cplusplus) && __GNUC_MINOR__ >= 8
64 # define SM__P(X)       __PMT(X)
65 #else /* __linux__ && __GNUC__ && __cplusplus && _GNUC_MINOR__ >= 8 */
66 # define SM__P(X)       __P(X)
67 #endif /* __linux__ && __GNUC__ && __cplusplus && _GNUC_MINOR__ >= 8 */
68
69 /* Some platforms don't define __P -- do it for them here: */
70 #ifndef __P
71 # ifdef __STDC__
72 #  define __P(X) X
73 # else /* __STDC__ */
74 #  define __P(X) ()
75 # endif /* __STDC__ */
76 #endif /* __P */
77
78 #if SM_CONF_STDBOOL_H
79 # include <stdbool.h>
80 #else /* SM_CONF_STDBOOL_H */
81 # ifndef __cplusplus
82 #  ifndef bool
83 #   ifndef __bool_true_false_are_defined
84 typedef int     bool;
85 #    define __bool_true_false_are_defined       1
86 #   endif /* ! __bool_true_false_are_defined */
87 #  endif /* bool */
88 # endif /* ! __cplusplus */
89 #endif /* SM_CONF_STDBOOL_H */
90
91 /*
92 **  structure describing one milter
93 */
94
95 struct smfiDesc
96 {
97         char            *xxfi_name;     /* filter name */
98         int             xxfi_version;   /* version code -- do not change */
99         unsigned long   xxfi_flags;     /* flags */
100
101         /* connection info filter */
102         sfsistat        (*xxfi_connect) SM__P((SMFICTX *, char *, _SOCK_ADDR *));
103
104         /* SMTP HELO command filter */
105         sfsistat        (*xxfi_helo) SM__P((SMFICTX *, char *));
106
107         /* envelope sender filter */
108         sfsistat        (*xxfi_envfrom) SM__P((SMFICTX *, char **));
109
110         /* envelope recipient filter */
111         sfsistat        (*xxfi_envrcpt) SM__P((SMFICTX *, char **));
112
113         /* header filter */
114         sfsistat        (*xxfi_header) SM__P((SMFICTX *, char *, char *));
115
116         /* end of header */
117         sfsistat        (*xxfi_eoh) SM__P((SMFICTX *));
118
119         /* body block */
120         sfsistat        (*xxfi_body) SM__P((SMFICTX *, unsigned char *, size_t));
121
122         /* end of message */
123         sfsistat        (*xxfi_eom) SM__P((SMFICTX *));
124
125         /* message aborted */
126         sfsistat        (*xxfi_abort) SM__P((SMFICTX *));
127
128         /* connection cleanup */
129         sfsistat        (*xxfi_close) SM__P((SMFICTX *));
130
131 #if SMFI_VERSION > 2
132         /* any unrecognized or unimplemented command filter */
133         sfsistat        (*xxfi_unknown) SM__P((SMFICTX *, char *));
134 #endif /* SMFI_VERSION > 2 */
135
136 #if SMFI_VERSION > 3
137         /* any unrecognized or unimplemented command filter */
138         sfsistat        (*xxfi_data) SM__P((SMFICTX *));
139 #endif /* SMFI_VERSION > 3 */
140 };
141
142 LIBMILTER_API int smfi_opensocket __P((bool));
143 LIBMILTER_API int smfi_register __P((struct smfiDesc));
144 LIBMILTER_API int smfi_main __P((void));
145 LIBMILTER_API int smfi_setbacklog __P((int));
146 LIBMILTER_API int smfi_setdbg __P((int));
147 LIBMILTER_API int smfi_settimeout __P((int));
148 LIBMILTER_API int smfi_setconn __P((char *));
149 LIBMILTER_API int smfi_stop __P((void));
150 #if _FFR_MAXDATASIZE
151 LIBMILTER_API size_t smfi_setmaxdatasize __P((size_t));
152 #endif /* _FFR_MAXDATASIZE */
153
154 /*
155 **  What the filter might do -- values to be ORed together for
156 **  smfiDesc.xxfi_flags.
157 */
158
159 #define SMFIF_NONE      0x00000000L     /* no flags */
160 #define SMFIF_ADDHDRS   0x00000001L     /* filter may add headers */
161 #define SMFIF_CHGBODY   0x00000002L     /* filter may replace body */
162 #define SMFIF_MODBODY   SMFIF_CHGBODY   /* backwards compatible */
163 #define SMFIF_ADDRCPT   0x00000004L     /* filter may add recipients */
164 #define SMFIF_DELRCPT   0x00000008L     /* filter may delete recipients */
165 #define SMFIF_CHGHDRS   0x00000010L     /* filter may change/delete headers */
166 #define SMFIF_QUARANTINE 0x00000020L    /* filter may quarantine envelope */
167
168 /*
169 **  Continue processing message/connection.
170 */
171
172 #define SMFIS_CONTINUE  0
173
174 /*
175 **  Reject the message/connection.
176 **  No further routines will be called for this message
177 **  (or connection, if returned from a connection-oriented routine).
178 */
179
180 #define SMFIS_REJECT    1
181
182 /*
183 **  Accept the message,
184 **  but silently discard the message.
185 **  No further routines will be called for this message.
186 **  This is only meaningful from message-oriented routines.
187 */
188
189 #define SMFIS_DISCARD   2
190
191 /*
192 **  Accept the message/connection.
193 **  No further routines will be called for this message
194 **  (or connection, if returned from a connection-oriented routine;
195 **  in this case, it causes all messages on this connection
196 **  to be accepted without filtering).
197 */
198
199 #define SMFIS_ACCEPT    3
200
201 /*
202 **  Return a temporary failure, i.e.,
203 **  the corresponding SMTP command will return a 4xx status code.
204 **  In some cases this may prevent further routines from
205 **  being called on this message or connection,
206 **  although in other cases (e.g., when processing an envelope
207 **  recipient) processing of the message will continue.
208 */
209
210 #define SMFIS_TEMPFAIL  4
211
212 #if 0
213 /*
214 **  Filter Routine Details
215 */
216
217 /* connection info filter */
218 extern sfsistat xxfi_connect __P((SMFICTX *, char *, _SOCK_ADDR *));
219
220 /*
221 **  xxfi_connect(ctx, hostname, hostaddr) Invoked on each connection
222 **
223 **      char *hostname; Host domain name, as determined by a reverse lookup
224 **              on the host address.
225 **      _SOCK_ADDR *hostaddr; Host address, as determined by a getpeername
226 **              call on the SMTP socket.
227 */
228
229 /* SMTP HELO command filter */
230 extern sfsistat xxfi_helo __P((SMFICTX *, char *));
231
232 /*
233 **  xxfi_helo(ctx, helohost) Invoked on SMTP HELO/EHLO command
234 **
235 **      char *helohost; Value passed to HELO/EHLO command, which should be
236 **              the domain name of the sending host (but is, in practice,
237 **              anything the sending host wants to send).
238 */
239
240 /* envelope sender filter */
241 extern sfsistat xxfi_envfrom __P((SMFICTX *, char **));
242
243 /*
244 **  xxfi_envfrom(ctx, argv) Invoked on envelope from
245 **
246 **      char **argv; Null-terminated SMTP command arguments;
247 **              argv[0] is guaranteed to be the sender address.
248 **              Later arguments are the ESMTP arguments.
249 */
250
251 /* envelope recipient filter */
252 extern sfsistat xxfi_envrcpt __P((SMFICTX *, char **));
253
254 /*
255 **  xxfi_envrcpt(ctx, argv) Invoked on each envelope recipient
256 **
257 **      char **argv; Null-terminated SMTP command arguments;
258 **              argv[0] is guaranteed to be the recipient address.
259 **              Later arguments are the ESMTP arguments.
260 */
261
262 /* unknown command filter */
263
264 extern sfsistat *xxfi_unknown __P((SMFICTX *, char *));
265
266 /*
267 **  xxfi_unknown(ctx, arg) Invoked when SMTP command is not recognized or not
268 **  implemented.
269 **      char *arg; Null-terminated SMTP command
270 */
271
272 /* header filter */
273 extern sfsistat xxfi_header __P((SMFICTX *, char *, char *));
274
275 /*
276 **  xxfi_header(ctx, headerf, headerv) Invoked on each message header. The
277 **  content of the header may have folded white space (that is, multiple
278 **  lines with following white space) included.
279 **
280 **      char *headerf; Header field name
281 **      char *headerv; Header field value
282 */
283
284 /* end of header */
285 extern sfsistat xxfi_eoh __P((SMFICTX *));
286
287 /*
288 **  xxfi_eoh(ctx) Invoked at end of header
289 */
290
291 /* body block */
292 extern sfsistat xxfi_body __P((SMFICTX *, unsigned char *, size_t));
293
294 /*
295 **  xxfi_body(ctx, bodyp, bodylen) Invoked for each body chunk. There may
296 **  be multiple body chunks passed to the filter. End-of-lines are
297 **  represented as received from SMTP (normally Carriage-Return/Line-Feed).
298 **
299 **      unsigned char *bodyp; Pointer to body data
300 **      size_t bodylen; Length of body data
301 */
302
303 /* end of message */
304 extern sfsistat xxfi_eom __P((SMFICTX *));
305
306 /*
307 **  xxfi_eom(ctx) Invoked at end of message. This routine can perform
308 **  special operations such as modifying the message header, body, or
309 **  envelope.
310 */
311
312 /* message aborted */
313 extern sfsistat xxfi_abort __P((SMFICTX *));
314
315 /*
316 **  xxfi_abort(ctx) Invoked if message is aborted outside of the control of
317 **  the filter, for example, if the SMTP sender issues an RSET command. If
318 **  xxfi_abort is called, xxfi_eom will not be called and vice versa.
319 */
320
321 /* connection cleanup */
322 extern sfsistat xxfi_close __P((SMFICTX *));
323
324 /*
325 **  xxfi_close(ctx) Invoked at end of the connection. This is called on
326 **  close even if the previous mail transaction was aborted.
327 */
328 #endif /* 0 */
329
330 /*
331 **  Additional information is passed in to the vendor filter routines using
332 **  symbols. Symbols correspond closely to sendmail macros. The symbols
333 **  defined depend on the context. The value of a symbol is accessed using:
334 */
335
336 /* Return the value of a symbol. */
337 LIBMILTER_API char * smfi_getsymval __P((SMFICTX *, char *));
338
339 /*
340 **  Return the value of a symbol.
341 **
342 **      SMFICTX *ctx; Opaque context structure
343 **      char *symname; The name of the symbol to access.
344 */
345
346 /*
347 **  Vendor filter routines that want to pass additional information back to
348 **  the MTA for use in SMTP replies may call smfi_setreply before returning.
349 */
350
351 LIBMILTER_API int smfi_setreply __P((SMFICTX *, char *, char *, char *));
352
353 /*
354 **  Alternatively, smfi_setmlreply can be called if a multi-line SMTP reply
355 **  is needed.
356 */
357
358 LIBMILTER_API int smfi_setmlreply __P((SMFICTX *, const char *, const char *, ...));
359
360 /*
361 **  Set the specific reply code to be used in response to the active
362 **  command. If not specified, a generic reply code is used.
363 **
364 **      SMFICTX *ctx; Opaque context structure
365 **      char *rcode; The three-digit (RFC 821) SMTP reply code to be
366 **              returned, e.g., ``551''.
367 **      char *xcode; The extended (RFC 2034) reply code, e.g., ``5.7.6''.
368 **      char *message; The text part of the SMTP reply.
369 */
370
371 /*
372 **  The xxfi_eom routine is called at the end of a message (essentially,
373 **  after the final DATA dot). This routine can call some special routines
374 **  to modify the envelope, header, or body of the message before the
375 **  message is enqueued. These routines must not be called from any vendor
376 **  routine other than xxfi_eom.
377 */
378
379 LIBMILTER_API int smfi_addheader __P((SMFICTX *, char *, char *));
380
381 /*
382 **  Add a header to the message. It is not checked for standards
383 **  compliance; the mail filter must ensure that no protocols are violated
384 **  as a result of adding this header.
385 **
386 **      SMFICTX *ctx; Opaque context structure
387 **      char *headerf; Header field name
388 **      char *headerv; Header field value
389 */
390
391 LIBMILTER_API int smfi_chgheader __P((SMFICTX *, char *, int, char *));
392
393 /*
394 **  Change/delete a header in the message.  It is not checked for standards
395 **  compliance; the mail filter must ensure that no protocols are violated
396 **  as a result of adding this header.
397 **
398 **      SMFICTX *ctx; Opaque context structure
399 **      char *headerf; Header field name
400 **      int index; The Nth occurence of header field name
401 **      char *headerv; New header field value (empty for delete header)
402 */
403
404 LIBMILTER_API int smfi_insheader __P((SMFICTX *, int, char *, char *));
405
406 /*
407 **  Insert a header into the message.  It is not checked for standards
408 **  compliance; the mail filter must ensure that no protocols are violated
409 **  as a result of adding this header.
410 **
411 **      SMFICTX *ctx; Opaque context structure
412 **      int idx; index into the header list where the insertion should happen
413 **      char *headerh; Header field name
414 **      char *headerv; Header field value
415 */
416
417 LIBMILTER_API int smfi_addrcpt __P((SMFICTX *, char *));
418
419 /*
420 **  Add a recipient to the envelope
421 **
422 **      SMFICTX *ctx; Opaque context structure
423 **      char *rcpt; Recipient to be added
424 */
425
426 LIBMILTER_API int smfi_delrcpt __P((SMFICTX *, char *));
427
428 /*
429 **  Send a "no-op" up to the MTA to tell it we're still alive, so long
430 **  milter-side operations don't time out.
431 **
432 **      SMFICTX *ctx; Opaque context structure
433 */
434
435 LIBMILTER_API int smfi_progress __P((SMFICTX *));
436
437 /*
438 **  Delete a recipient from the envelope
439 **
440 **      SMFICTX *ctx; Opaque context structure
441 **      char *rcpt; Envelope recipient to be deleted. This should be in
442 **              exactly the form passed to xxfi_envrcpt or the address may
443 **              not be deleted.
444 */
445
446 LIBMILTER_API int smfi_replacebody __P((SMFICTX *, unsigned char *, int));
447
448 /*
449 **  Replace the body of the message. This routine may be called multiple
450 **  times if the body is longer than convenient to send in one call. End of
451 **  line should be represented as Carriage-Return/Line Feed.
452 **
453 **      char *bodyp; Pointer to block of body information to insert
454 **      int bodylen; Length of data pointed at by bodyp
455 */
456
457 /*
458 **  If the message is aborted (for example, if the SMTP sender sends the
459 **  envelope but then does a QUIT or RSET before the data is sent),
460 **  xxfi_abort is called. This can be used to reset state.
461 */
462
463 /*
464 **  Quarantine an envelope
465 **
466 **      SMFICTX *ctx; Opaque context structure
467 **      char *reason: explanation
468 */
469
470 LIBMILTER_API int smfi_quarantine __P((SMFICTX *ctx, char *reason));
471
472 /*
473 **  Connection-private data (specific to an SMTP connection) can be
474 **  allocated using the smfi_setpriv routine; routines can access private
475 **  data using smfi_getpriv.
476 */
477
478 LIBMILTER_API int smfi_setpriv __P((SMFICTX *, void *));
479
480 /*
481 **  Set the private data pointer
482 **
483 **      SMFICTX *ctx; Opaque context structure
484 **      void *privatedata; Pointer to private data area
485 */
486
487 LIBMILTER_API void *smfi_getpriv __P((SMFICTX *));
488
489 #ifdef __cplusplus
490 }
491 #endif /* __cplusplus */
492
493 #endif /* ! _LIBMILTER_MFAPI_H */