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