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 */