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