]> git.sur5r.net Git - openldap/blob - include/rewrite.h
ITS#8789 avoid unnecessary writes of context entry
[openldap] / include / rewrite.h
1 /* $OpenLDAP$
2  */
3 /* This work is part of OpenLDAP Software <http://www.openldap.org/>.
4  *
5  * Copyright 2000-2017 The OpenLDAP Foundation.
6  * Portions Copyright 2000-2003 Pierangelo Masarati.
7  * All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted only as authorized by the OpenLDAP
11  * Public License.
12  *
13  * A copy of this license is available in file LICENSE in the
14  * top-level directory of the distribution or, alternatively, at
15  * <http://www.OpenLDAP.org/license.html>.
16  */
17 /* ACKNOWLEDGEMENT:
18  * This work was initially developed by Pierangelo Masarati for
19  * inclusion in OpenLDAP Software.
20  */
21
22 #ifndef REWRITE_H
23 #define REWRITE_H
24
25 /*
26  * Default rewrite context
27  */
28 #define REWRITE_DEFAULT_CONTEXT         "default"
29
30 /*
31  * Rewrite engine states
32  */
33 #define REWRITE_OFF                     0x0000
34 #define REWRITE_ON                      0x0001
35 #define REWRITE_DEFAULT                 REWRITE_OFF
36
37 /*
38  * Rewrite internal status returns
39  */
40 #define REWRITE_SUCCESS                 LDAP_SUCCESS
41 #define REWRITE_ERR                     LDAP_OTHER
42
43 /*
44  * Rewrite modes (input values for rewrite_info_init); determine the
45  * behavior in case a null or non existent context is required:
46  *
47  *      REWRITE_MODE_ERR                error
48  *      REWRITE_MODE_OK                 no error but no rewrite
49  *      REWRITE_MODE_COPY_INPUT         a copy of the input is returned
50  *      REWRITE_MODE_USE_DEFAULT        the default context is used.
51  */
52 #define REWRITE_MODE_ERR                0x0010
53 #define REWRITE_MODE_OK                 0x0011
54 #define REWRITE_MODE_COPY_INPUT         0x0012
55 #define REWRITE_MODE_USE_DEFAULT        0x0013
56
57 /*
58  * Rewrite status returns
59  *
60  *      REWRITE_REGEXEC_OK              success (result may be empty in case
61  *                                      of no match)
62  *      REWRITE_REGEXEC_ERR             error (internal error,
63  *                                      misconfiguration, map not working ...)
64  *      REWRITE_REGEXEC_STOP            internal use; never returned
65  *      REWRITE_REGEXEC_UNWILLING       the server should issue an 'unwilling
66  *                                      to perform' error
67  */
68 #define REWRITE_REGEXEC_OK              (0)
69 #define REWRITE_REGEXEC_ERR             (-1)
70 #define REWRITE_REGEXEC_STOP            (-2)
71 #define REWRITE_REGEXEC_UNWILLING       (-3)
72 #define REWRITE_REGEXEC_USER            (1)     /* and above: LDAP errors */
73
74 /*
75  * Rewrite variable flags
76  *      REWRITE_VAR_INSERT              insert mode (default) when adding
77  *                                      a variable; if not set during value
78  *                                      update, the variable is not inserted
79  *                                      if not present
80  *      REWRITE_VAR_UPDATE              update mode (default) when updating
81  *                                      a variable; if not set during insert,
82  *                                      the value is not updated if the
83  *                                      variable already exists
84  *      REWRITE_VAR_COPY_NAME           copy the variable name; if not set,
85  *                                      the name is not copied; be sure the
86  *                                      referenced string is available for
87  *                                      the entire life scope of the variable.
88  *      REWRITE_VAR_COPY_VALUE          copy the variable value; if not set,
89  *                                      the value is not copied; be sure the
90  *                                      referenced string is available for
91  *                                      the entire life scope of the variable.
92  */
93 #define REWRITE_VAR_NONE                0x0000
94 #define REWRITE_VAR_INSERT              0x0001
95 #define REWRITE_VAR_UPDATE              0x0002
96 #define REWRITE_VAR_COPY_NAME           0x0004
97 #define REWRITE_VAR_COPY_VALUE          0x0008
98
99 /*
100  * Rewrite info
101  */
102 struct rewrite_info;
103
104 struct berval; /* avoid include */
105
106 LDAP_BEGIN_DECL
107
108 /*
109  * Inits the info
110  */
111 LDAP_REWRITE_F (struct rewrite_info *)
112 rewrite_info_init(
113                 int mode
114 );
115
116 /*
117  * Cleans up the info structure
118  */
119 LDAP_REWRITE_F (int)
120 rewrite_info_delete(
121                 struct rewrite_info **info
122 );
123
124
125 /*
126  * Parses a config line and takes actions to fit content in rewrite structure;
127  * lines handled are of the form:
128  *
129  *      rewriteEngine           {on|off}
130  *      rewriteMaxPasses        numPasses
131  *      rewriteContext          contextName [alias aliasedRewriteContex]
132  *      rewriteRule             pattern substPattern [ruleFlags]
133  *      rewriteMap              mapType mapName [mapArgs]
134  *      rewriteParam            paramName paramValue
135  */
136 LDAP_REWRITE_F (int)
137 rewrite_parse(
138                 struct rewrite_info *info,
139                 const char *fname,
140                 int lineno,
141                 int argc,
142                 char **argv
143 );
144
145 /*
146  * process a config file that was already opened. Uses rewrite_parse.
147  */
148 LDAP_REWRITE_F (int)
149 rewrite_read(
150                 FILE *fin,
151                 struct rewrite_info *info
152 );
153
154 /*
155  * Rewrites a string according to context.
156  * If the engine is off, OK is returned, but the return string will be NULL.
157  * In case of 'unwilling to perform', UNWILLING is returned, and the
158  * return string will also be null. The same in case of error.
159  * Otherwise, OK is returned, and result will hold a newly allocated string
160  * with the rewriting.
161  *
162  * What to do in case of non-existing rewrite context is still an issue.
163  * Four possibilities:
164  *      - error,
165  *      - ok with NULL result,
166  *      - ok with copy of string as result,
167  *      - use the default rewrite context.
168  */
169 LDAP_REWRITE_F (int)
170 rewrite(
171                 struct rewrite_info *info,
172                 const char *rewriteContext,
173                 const char *string,
174                 char **result
175 );
176
177 /*
178  * Same as above; the cookie relates the rewrite to a session
179  */
180 LDAP_REWRITE_F (int)
181 rewrite_session(
182                 struct rewrite_info *info,
183                 const char *rewriteContext,
184                 const char *string,
185                 const void *cookie,
186                 char **result
187 );
188
189 /*
190  * Inits a session
191  */
192 LDAP_REWRITE_F (struct rewrite_session *)
193 rewrite_session_init(
194                 struct rewrite_info *info,
195                 const void *cookie
196 );
197
198 /*
199  * Defines and inits a variable with session scope
200  */
201 LDAP_REWRITE_F (int)
202 rewrite_session_var_set_f(
203                 struct rewrite_info *info,
204                 const void *cookie,
205                 const char *name,
206                 const char *value,
207                 int flags
208 );
209
210 #define rewrite_session_var_set(info, cookie, name, value) \
211         rewrite_session_var_set_f((info), (cookie), (name), (value), \
212                         REWRITE_VAR_INSERT|REWRITE_VAR_UPDATE|REWRITE_VAR_COPY_NAME|REWRITE_VAR_COPY_VALUE)
213
214 /*
215  * Deletes a session
216  */
217 LDAP_REWRITE_F (int)
218 rewrite_session_delete(
219                 struct rewrite_info *info,
220                 const void *cookie
221 );
222
223
224 /*
225  * Params
226  */
227
228 /*
229  * Defines and inits a variable with global scope
230  */
231 LDAP_REWRITE_F (int)
232 rewrite_param_set(
233                 struct rewrite_info *info,
234                 const char *name,
235                 const char *value
236 );
237
238 /*
239  * Gets a var with global scope
240  */
241 LDAP_REWRITE_F (int)
242 rewrite_param_get(
243                 struct rewrite_info *info,
244                 const char *name,
245                 struct berval *value
246 );
247
248 /*
249  * Destroys the parameter tree
250  */
251 LDAP_REWRITE_F (int)
252 rewrite_param_destroy(
253                 struct rewrite_info *info
254 );
255
256 /*
257  * Mapping implementations
258  */
259
260 struct rewrite_mapper;
261
262 typedef void * (rewrite_mapper_config)(
263         const char *fname,
264         int lineno,
265         int argc,
266         char **argv );
267
268 typedef int (rewrite_mapper_apply)(
269         void *ctx,
270         const char *arg,
271         struct berval *retval );
272
273 typedef int (rewrite_mapper_destroy)(
274         void *ctx );
275
276 typedef struct rewrite_mapper {
277         char *rm_name;
278         rewrite_mapper_config *rm_config;
279         rewrite_mapper_apply *rm_apply;
280         rewrite_mapper_destroy *rm_destroy;
281 } rewrite_mapper;
282
283 /* For dynamic loading and unloading of mappers */
284 LDAP_REWRITE_F (int)
285 rewrite_mapper_register(
286         const rewrite_mapper *map );
287
288 LDAP_REWRITE_F (int)
289 rewrite_mapper_unregister(
290         const rewrite_mapper *map );
291
292 LDAP_REWRITE_F (const rewrite_mapper *)
293 rewrite_mapper_find(
294         const char *name );
295
296 LDAP_END_DECL
297
298 #endif /* REWRITE_H */