Docs: more notes for local_scan/dlfunc
[exim.git] / src / src / local_scan.h
CommitLineData
059ec3d9
PH
1/*************************************************
2* Exim - an Internet mail transport agent *
3*************************************************/
4
9b230009 5/* Copyright (c) University of Cambridge 1995 - 2019 */
059ec3d9
PH
6/* See the file NOTICE for conditions of use and distribution. */
7
8/* This file is the header that is the only Exim header to be included in the
9source for the local_scan.c() function. It contains definitions that are made
9b230009
JH
10available for use in that function, and which are documented. That source
11should first #define LOCAL_SCAN
1a46a8c5 12
f0ed88da 13This API is also used for functions called by the ${dlfunc expansion item.
9b230009 14Source for those should first #define DLFUNC_IMPL and then include this file.
f0ed88da
JH
15Coders of dlfunc routines should read the notes on tainting at the start of
16store.c
17*/
059ec3d9
PH
18
19
750af86e
PH
20/* Some basic types that make some things easier, the Exim configuration
21settings, and the store functions. */
059ec3d9 22
ce552449 23#include <stdarg.h>
059ec3d9 24#include <sys/types.h>
750af86e 25#include "config.h"
059ec3d9
PH
26#include "mytypes.h"
27#include "store.h"
28
29
30/* The function and its return codes. */
31
32extern int local_scan(int, uschar **);
33
34enum {
35 LOCAL_SCAN_ACCEPT, /* Accept */
36 LOCAL_SCAN_ACCEPT_FREEZE, /* Accept, but freeze */
37 LOCAL_SCAN_ACCEPT_QUEUE, /* Accept, but no immediate delivery */
38 LOCAL_SCAN_REJECT, /* Permanent rejection */
39 LOCAL_SCAN_REJECT_NOLOGHDR, /* Permanent rejection, no log header */
40 LOCAL_SCAN_TEMPREJECT, /* Temporary rejection */
41 LOCAL_SCAN_TEMPREJECT_NOLOGHDR /* Temporary rejection, no log header */
42};
43
44
1a46a8c5
PH
45/* Functions called by ${dlfunc{file}{func}{arg}...} return one of the five
46status codes defined immediately below. The function's first argument is either
47the result of expansion, or the error message in case of failure. The second
48and third arguments are standard argument count and vector, comprising the
49{arg} values specified in the expansion item. */
50
51typedef int exim_dlfunc_t(uschar **yield, int argc, uschar *argv[]);
52
53
54/* Return codes from the support functions lss_match_xxx(). These are also the
55codes that dynamically-loaded ${dlfunc functions must return. */
059ec3d9
PH
56
57#define OK 0 /* Successful match */
58#define DEFER 1 /* Defer - some problem */
59#define FAIL 2 /* Matching failed */
60#define ERROR 3 /* Internal or config error */
61
1a46a8c5
PH
62/* Extra return code for ${dlfunc functions */
63
64#define FAIL_FORCED 4 /* "Forced" failure */
65
059ec3d9
PH
66
67/* Available logging destinations */
68
69#define LOG_MAIN 1 /* Write to the main log */
70#define LOG_PANIC 2 /* Write to the panic log */
71#define LOG_REJECT 16 /* Write to the reject log, with headers */
72
73
74/* Accessible debugging bits */
75
76#define D_v 0x00000001
77#define D_local_scan 0x00000002
78
79
80/* Option types that can be used for local_scan_options. The boolean ones
81MUST be last so that they are contiguous with the internal boolean specials. */
82
83enum { opt_stringptr, opt_int, opt_octint, opt_mkint, opt_Kint, opt_fixed,
84 opt_time, opt_bool };
85
86
87/* The length of message identification strings. This is the id used internally
88by exim. The external version for use in Received: strings has a leading 'E'
89added to ensure it starts with a letter. */
90
91#define MESSAGE_ID_LENGTH 16
92
93/* The offset to the start of the data in the data file - this allows for
94the name of the data file to be present in the first line. */
95
96#define SPOOL_DATA_START_OFFSET (MESSAGE_ID_LENGTH+3)
97
98/* Some people (Marc Merlin et al) are maintaining a patch that allows for
99dynamic local_scan() libraries. This code is not yet in Exim proper, but it
100helps the maintainers if we keep their ABI version numbers here. This may
101mutate into more general support later. The major number is increased when the
102ABI is changed in a non backward compatible way. The minor number is increased
103each time a new feature is added (in a way that doesn't break backward
104compatibility). */
105
b3317cfa 106#define LOCAL_SCAN_ABI_VERSION_MAJOR 3
b4a15239 107#define LOCAL_SCAN_ABI_VERSION_MINOR 1
e57faad2
MH
108#define LOCAL_SCAN_ABI_VERSION \
109 LOCAL_SCAN_ABI_VERSION_MAJOR.LOCAL_SCAN_ABI_VERSION_MINOR
059ec3d9
PH
110
111/* Structure definitions that are documented as visible in the function. */
112
113typedef struct header_line {
114 struct header_line *next;
115 int type;
116 int slen;
117 uschar *text;
118} header_line;
119
120/* Entries in lists options are in this form. */
121
122typedef struct {
863bd541 123 const char *name; /* should have been uschar but too late now */
1ba28e2b
PP
124 int type;
125 void *value;
059ec3d9
PH
126} optionlist;
127
d81d33cf 128/* Structure for holding information about an envelope address. The errors_to
059ec3d9
PH
129field is always NULL except for one_time aliases that had errors_to on the
130routers that generated them. */
131
132typedef struct recipient_item {
133 uschar *address; /* the recipient address */
134 int pno; /* parent number for "one_time" alias, or -1 */
135 uschar *errors_to; /* the errors_to address or NULL */
6c1c3d1d
WB
136 uschar *orcpt; /* DSN orcpt */
137 int dsn_flags; /* DSN flags */
8523533c
TK
138#ifdef EXPERIMENTAL_BRIGHTMAIL
139 uschar *bmi_optin;
140#endif
059ec3d9
PH
141} recipient_item;
142
143
144/* Global variables that are documented as visible in the function. */
145
146extern unsigned int debug_selector; /* Debugging bits */
147
2b85bce7
PH
148extern int body_linecount; /* Line count in body */
149extern int body_zerocount; /* Binary zero count in body */
059ec3d9
PH
150extern uschar *expand_string_message; /* Error info for failing expansion */
151extern uschar *headers_charset; /* Charset for RFC 2047 decoding */
152extern header_line *header_last; /* Final header */
153extern header_line *header_list; /* First header */
154extern BOOL host_checking; /* Set when checking a host */
155extern uschar *interface_address; /* Interface for incoming call */
156extern int interface_port; /* Port number for incoming call */
157extern uschar *message_id; /* Internal id of message being handled */
158extern uschar *received_protocol; /* Name of incoming protocol */
159extern int recipients_count; /* Number of recipients */
160extern recipient_item *recipients_list;/* List of recipient addresses */
161extern unsigned char *sender_address; /* Sender address */
162extern uschar *sender_host_address; /* IP address of sender, as chars */
163extern uschar *sender_host_authenticated; /* Name of authentication mechanism */
164extern uschar *sender_host_name; /* Host name from lookup */
165extern int sender_host_port; /* Port number of sender */
166extern BOOL smtp_batched_input; /* TRUE if SMTP batch (no interaction) */
167extern BOOL smtp_input; /* TRUE if input is via SMTP */
168
169
170/* Functions that are documented as visible in local_scan(). */
171
172extern int child_close(pid_t, int);
173extern pid_t child_open(uschar **, uschar **, int, int *, int *, BOOL);
174extern pid_t child_open_exim(int *);
5977a0b3 175extern pid_t child_open_exim2(int *, uschar *, uschar *);
1ba28e2b 176extern void debug_printf(const char *, ...) PRINTF_FUNCTION(1,2);
059ec3d9 177extern uschar *expand_string(uschar *);
1ba28e2b
PP
178extern void header_add(int, const char *, ...);
179extern void header_add_at_position(BOOL, uschar *, BOOL, int, const char *, ...);
180extern void header_remove(int, const uschar *);
181extern BOOL header_testname(header_line *, const uschar *, int, BOOL);
182extern BOOL header_testname_incomplete(header_line *, const uschar *, int, BOOL);
e0df1c83 183extern void log_write(unsigned int, int, const char *format, ...) PRINTF_FUNCTION(3,4);
059ec3d9
PH
184extern int lss_b64decode(uschar *, uschar **);
185extern uschar *lss_b64encode(uschar *, int);
186extern int lss_match_domain(uschar *, uschar *);
187extern int lss_match_local_part(uschar *, uschar *, BOOL);
188extern int lss_match_address(uschar *, uschar *, BOOL);
189extern int lss_match_host(uschar *, uschar *, uschar *);
190extern void receive_add_recipient(uschar *, int);
191extern BOOL receive_remove_recipient(uschar *);
192extern uschar *rfc2047_decode(uschar *, BOOL, uschar *, int, int *, uschar **);
193extern int smtp_fflush(void);
925ac8e4
JH
194extern void smtp_printf(const char *, BOOL, ...) PRINTF_FUNCTION(1,3);
195extern void smtp_vprintf(const char *, BOOL, va_list);
f3ebb786
JH
196
197#define string_sprintf(fmt, ...) \
c4efe382 198 string_sprintf_trc(fmt, US __FUNCTION__, __LINE__, __VA_ARGS__)
f3ebb786 199extern uschar *string_sprintf_trc(const char *, const uschar *, unsigned, ...) ALMOST_PRINTF(1,4);
059ec3d9 200
4ec0fcb6
JH
201#define store_get(size, tainted) \
202 store_get_3(size, tainted, __FUNCTION__, __LINE__)
203extern void *store_get_3(int, BOOL, const char *, int) ALLOC ALLOC_SIZE(1) WARN_UNUSED_RESULT;
204#define store_get_perm(size, tainted) \
205 store_get_perm_3(size, tainted, __FUNCTION__, __LINE__)
206extern void *store_get_perm_3(int, BOOL, const char *, int) ALLOC ALLOC_SIZE(1) WARN_UNUSED_RESULT;
207
208
8b5d88d2 209#if defined(LOCAL_SCAN) || defined(DLFUNC_IMPL)
e59797e3
JH
210/* When compiling a local_scan() file we want to rename a published API, so that
211we can use an inlined implementation in the compiles of the main Exim files,
212with the original name. */
213
214# define string_copy(s) string_copy_function(s)
d48326c0
JH
215# define string_copyn(s, n) string_copyn_function((s), (n))
216# define string_copy_taint(s, t) string_copy_taint_function((s), (t))
e59797e3
JH
217
218extern uschar * string_copy_function(const uschar *);
b4a15239
JH
219extern uschar * string_copyn_function(const uschar *, int n);
220extern uschar * string_copy_taint_function(const uschar *, BOOL tainted);
e59797e3
JH
221#endif
222
059ec3d9 223/* End of local_scan.h */