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