f10e584f87493d9ac221932cb3a70db13e7adc9a
[kamenim/samba.git] / source4 / lib / ldb / include / ldb_module.h
1 /*
2    ldb database library
3
4    Copyright (C) Simo Sorce         2008
5
6      ** NOTE! The following LGPL license applies to the ldb
7      ** library. This does NOT imply that all of Samba is released
8      ** under the LGPL
9
10    This library is free software; you can redistribute it and/or
11    modify it under the terms of the GNU Lesser General Public
12    License as published by the Free Software Foundation; either
13    version 3 of the License, or (at your option) any later version.
14
15    This library is distributed in the hope that it will be useful,
16    but WITHOUT ANY WARRANTY; without even the implied warranty of
17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18    Lesser General Public License for more details.
19
20    You should have received a copy of the GNU Lesser General Public
21    License along with this library; if not, see <http://www.gnu.org/licenses/>.
22 */
23
24 /*
25  *  Name: ldb
26  *
27  *  Component: ldb module header
28  *
29  *  Description: defines ldb modules structures and helpers
30  *
31  */
32
33 #ifndef _LDB_MODULE_H_
34 #define _LDB_MODULE_H_
35
36 #include "ldb.h"
37
38 struct ldb_context;
39 struct ldb_module;
40
41 /**
42    internal flag bits on message elements. Must be within LDB_FLAG_INTERNAL_MASK
43  */
44 #define LDB_FLAG_INTERNAL_DISABLE_VALIDATION 0x10
45
46
47 /*
48    these function pointers define the operations that a ldb module can intercept
49 */
50 struct ldb_module_ops {
51         const char *name;
52         int (*init_context) (struct ldb_module *);
53         int (*search)(struct ldb_module *, struct ldb_request *); /* search */
54         int (*add)(struct ldb_module *, struct ldb_request *); /* add */
55         int (*modify)(struct ldb_module *, struct ldb_request *); /* modify */
56         int (*del)(struct ldb_module *, struct ldb_request *); /* delete */
57         int (*rename)(struct ldb_module *, struct ldb_request *); /* rename */
58         int (*request)(struct ldb_module *, struct ldb_request *); /* match any other operation */
59         int (*extended)(struct ldb_module *, struct ldb_request *); /* extended operations */
60         int (*start_transaction)(struct ldb_module *);
61         int (*prepare_commit)(struct ldb_module *);
62         int (*end_transaction)(struct ldb_module *);
63         int (*del_transaction)(struct ldb_module *);
64         int (*sequence_number)(struct ldb_module *, struct ldb_request *);
65         void *private_data;
66 };
67
68
69 /* The following definitions come from lib/ldb/common/ldb_debug.c  */
70 void ldb_debug(struct ldb_context *ldb, enum ldb_debug_level level, const char *fmt, ...) PRINTF_ATTRIBUTE(3, 4);
71 void ldb_debug_set(struct ldb_context *ldb, enum ldb_debug_level level, 
72                    const char *fmt, ...) PRINTF_ATTRIBUTE(3, 4);
73 void ldb_debug_add(struct ldb_context *ldb, const char *fmt, ...) PRINTF_ATTRIBUTE(2, 3);
74 void ldb_debug_end(struct ldb_context *ldb, enum ldb_debug_level level);
75
76 #define ldb_error(ldb, ecode, reason) ldb_error_at(ldb, ecode, reason, __FILE__, __LINE__)
77
78 #define ldb_oom(ldb) ldb_error(ldb, LDB_DEBUG_FATAL, "ldb out of memory")
79 #define ldb_module_oom(module) ldb_oom(ldb_module_get_ctx(module))
80 #define ldb_operr(ldb) ldb_error(ldb, LDB_ERR_OPERATIONS_ERROR, "operations error")
81
82 /* The following definitions come from lib/ldb/common/ldb.c  */
83
84 void ldb_request_set_state(struct ldb_request *req, int state);
85 int ldb_request_get_status(struct ldb_request *req);
86
87 unsigned int ldb_get_create_perms(struct ldb_context *ldb);
88
89 const struct ldb_schema_syntax *ldb_standard_syntax_by_name(struct ldb_context *ldb,
90                                                             const char *syntax);
91
92 /* The following definitions come from lib/ldb/common/ldb_attributes.c  */
93
94 int ldb_schema_attribute_add_with_syntax(struct ldb_context *ldb,
95                                          const char *name,
96                                          unsigned flags,
97                                          const struct ldb_schema_syntax *syntax);
98 int ldb_schema_attribute_add(struct ldb_context *ldb, 
99                              const char *name,
100                              unsigned flags,
101                              const char *syntax);
102 void ldb_schema_attribute_remove(struct ldb_context *ldb, const char *name);
103
104 /* we allow external code to override the name -> schema_attribute function */
105 typedef const struct ldb_schema_attribute *(*ldb_attribute_handler_override_fn_t)(struct ldb_context *, void *, const char *);
106
107 void ldb_schema_attribute_set_override_handler(struct ldb_context *ldb,
108                                                ldb_attribute_handler_override_fn_t override,
109                                                void *private_data);
110
111 /* A useful function to build comparison functions with */
112 int ldb_any_comparison(struct ldb_context *ldb, void *mem_ctx, 
113                        ldb_attr_handler_t canonicalise_fn, 
114                        const struct ldb_val *v1,
115                        const struct ldb_val *v2);
116
117 /* The following definitions come from lib/ldb/common/ldb_controls.c  */
118 struct ldb_control *get_control_from_list(struct ldb_control **controls, const char *oid);
119 int save_controls(struct ldb_control *exclude, struct ldb_request *req, struct ldb_control ***saver);
120 /* Returns a list of controls, except the one specified.  Included
121  * controls become a child of returned list if they were children of
122  * controls_in */
123 struct ldb_control **controls_except_specified(struct ldb_control **controls_in, 
124                                                TALLOC_CTX *mem_ctx, 
125                                                struct ldb_control *exclude);
126 int check_critical_controls(struct ldb_control **controls);
127
128 /* The following definitions come from lib/ldb/common/ldb_ldif.c  */
129 int ldb_should_b64_encode(struct ldb_context *ldb, const struct ldb_val *val);
130
131 /* The following definitions come from lib/ldb/common/ldb_match.c  */
132 int ldb_match_msg(struct ldb_context *ldb,
133                   const struct ldb_message *msg,
134                   const struct ldb_parse_tree *tree,
135                   struct ldb_dn *base,
136                   enum ldb_scope scope);
137
138 int ldb_match_msg_error(struct ldb_context *ldb,
139                         const struct ldb_message *msg,
140                         const struct ldb_parse_tree *tree,
141                         struct ldb_dn *base,
142                         enum ldb_scope scope,
143                         bool *matched);
144
145 int ldb_match_msg_objectclass(const struct ldb_message *msg,
146                               const char *objectclass);
147
148 /* The following definitions come from lib/ldb/common/ldb_modules.c  */
149
150 struct ldb_module *ldb_module_new(TALLOC_CTX *memctx,
151                                   struct ldb_context *ldb,
152                                   const char *module_name,
153                                   const struct ldb_module_ops *ops);
154
155 const char * ldb_module_get_name(struct ldb_module *module);
156 struct ldb_context *ldb_module_get_ctx(struct ldb_module *module);
157 void *ldb_module_get_private(struct ldb_module *module);
158 void ldb_module_set_private(struct ldb_module *module, void *private_data);
159 const struct ldb_module_ops *ldb_module_get_ops(struct ldb_module *module);
160
161 int ldb_next_request(struct ldb_module *module, struct ldb_request *request);
162 int ldb_next_start_trans(struct ldb_module *module);
163 int ldb_next_end_trans(struct ldb_module *module);
164 int ldb_next_del_trans(struct ldb_module *module);
165 int ldb_next_prepare_commit(struct ldb_module *module);
166 int ldb_next_init(struct ldb_module *module);
167
168 void ldb_set_errstring(struct ldb_context *ldb, const char *err_string);
169 void ldb_asprintf_errstring(struct ldb_context *ldb, const char *format, ...) PRINTF_ATTRIBUTE(2,3);
170 void ldb_reset_err_string(struct ldb_context *ldb);
171 int ldb_error_at(struct ldb_context *ldb, int ecode, const char *reason, const char *file, int line);
172
173 const char *ldb_default_modules_dir(void);
174
175 int ldb_register_module(const struct ldb_module_ops *);
176
177 typedef int (*ldb_connect_fn)(struct ldb_context *ldb, const char *url,
178                               unsigned int flags, const char *options[],
179                               struct ldb_module **module);
180
181 struct ldb_backend_ops {
182         const char *name;
183         ldb_connect_fn connect_fn;
184 };
185
186 const char *ldb_default_modules_dir(void);
187
188 int ldb_register_backend(const char *url_prefix, ldb_connect_fn, bool);
189
190 struct ldb_handle *ldb_handle_new(TALLOC_CTX *mem_ctx, struct ldb_context *ldb);
191
192 int ldb_module_send_entry(struct ldb_request *req,
193                           struct ldb_message *msg,
194                           struct ldb_control **ctrls);
195
196 int ldb_module_send_referral(struct ldb_request *req,
197                                            char *ref);
198
199 int ldb_module_done(struct ldb_request *req,
200                     struct ldb_control **ctrls,
201                     struct ldb_extended *response,
202                     int error);
203
204 int ldb_mod_register_control(struct ldb_module *module, const char *oid);
205
206 void ldb_set_default_dns(struct ldb_context *ldb);
207 /**
208   Add a ldb_control to a ldb_reply
209
210   \param ares the reply struct where to add the control
211   \param oid the object identifier of the control as string
212   \param critical whether the control should be critical or not
213   \param data a talloc pointer to the control specific data
214
215   \return result code (LDB_SUCCESS on success, or a failure code)
216 */
217 int ldb_reply_add_control(struct ldb_reply *ares, const char *oid, bool critical, void *data);
218
219 /**
220   mark a request as untrusted. This tells the rootdse module to remove
221   unregistered controls
222  */
223 void ldb_req_mark_untrusted(struct ldb_request *req);
224
225 /**
226    return true is a request is untrusted
227  */
228 bool ldb_req_is_untrusted(struct ldb_request *req);
229
230 /* load all modules from the given directory */
231 int ldb_modules_load(const char *modules_path, const char *version);
232
233 /* init functions prototype */
234 typedef int (*ldb_module_init_fn)(const char *);
235
236 /*
237   general ldb hook function
238  */
239 enum ldb_module_hook_type { LDB_MODULE_HOOK_CMDLINE_OPTIONS     = 1,
240                             LDB_MODULE_HOOK_CMDLINE_PRECONNECT  = 2,
241                             LDB_MODULE_HOOK_CMDLINE_POSTCONNECT = 3 };
242
243 typedef int (*ldb_hook_fn)(struct ldb_context *, enum ldb_module_hook_type );
244
245 /*
246   register a ldb hook function
247  */
248 int ldb_register_hook(ldb_hook_fn hook_fn);
249
250 /*
251   call ldb hooks of a given type
252  */
253 int ldb_modules_hook(struct ldb_context *ldb, enum ldb_module_hook_type t);
254
255 #define LDB_MODULE_CHECK_VERSION(version) do { \
256  if (strcmp(version, LDB_VERSION) != 0) { \
257         fprintf(stderr, "ldb: module version mismatch in %s : ldb_version=%s module_version=%s\n", \
258                         __FILE__, version, LDB_VERSION); \
259         return LDB_ERR_UNAVAILABLE; \
260  }} while (0)
261
262
263 /*
264   return a string representation of the calling chain for the given
265   ldb request
266  */
267 char *ldb_module_call_chain(struct ldb_request *req, TALLOC_CTX *mem_ctx);
268
269 /*
270   return the next module in the chain
271  */
272 struct ldb_module *ldb_module_next(struct ldb_module *module);
273
274 /*
275   set the next module in the module chain
276  */
277 void ldb_module_set_next(struct ldb_module *module, struct ldb_module *next);
278
279 /*
280   load a list of modules
281  */
282 int ldb_module_load_list(struct ldb_context *ldb, const char **module_list,
283                          struct ldb_module *backend, struct ldb_module **out);
284
285 /*
286   get the popt_options pointer in the ldb structure. This allows a ldb
287   module to change the command line parsing
288  */
289 struct poptOption **ldb_module_popt_options(struct ldb_context *ldb);
290
291 /* modules are called in inverse order on the stack.
292    Lets place them as an admin would think the right order is.
293    Modules order is important */
294 const char **ldb_modules_list_from_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *string);
295
296 /*
297   return the current ldb flags LDB_FLG_*
298  */
299 uint32_t ldb_module_flags(struct ldb_context *ldb);
300
301 int ldb_module_connect_backend(struct ldb_context *ldb,
302                                const char *url,
303                                const char *options[],
304                                struct ldb_module **backend_module);
305
306 /*
307   initialise a chain of modules
308  */
309 int ldb_module_init_chain(struct ldb_context *ldb, struct ldb_module *module);
310
311
312 #endif