89e88fd4e975b0e15f5ee78047d2a29f94820b48
[sfrench/samba-autobuild/.git] / source4 / lib / ldb / include / ldb.h
1 /* 
2    ldb database library
3
4    Copyright (C) Andrew Tridgell  2004
5    Copyright (C) Stefan Metzmacher  2004
6
7      ** NOTE! The following LGPL license applies to the ldb
8      ** library. This does NOT imply that all of Samba is released
9      ** under the LGPL
10    
11    This library is free software; you can redistribute it and/or
12    modify it under the terms of the GNU Lesser General Public
13    License as published by the Free Software Foundation; either
14    version 2 of the License, or (at your option) any later version.
15
16    This library is distributed in the hope that it will be useful,
17    but WITHOUT ANY WARRANTY; without even the implied warranty of
18    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
19    Lesser General Public License for more details.
20
21    You should have received a copy of the GNU Lesser General Public
22    License along with this library; if not, write to the Free Software
23    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
24 */
25
26 /*
27  *  Name: ldb
28  *
29  *  Component: ldb header
30  *
31  *  Description: defines for base ldb API
32  *
33  *  Author: Andrew Tridgell
34  *  Author: Stefan Metzmacher
35  */
36
37 #ifndef _LDB_H_
38 #define _LDB_H_ 1
39
40 /*
41   major restrictions as compared to normal LDAP:
42
43      - no async calls.
44      - each record must have a unique key field
45      - the key must be representable as a NULL terminated C string and may not 
46        contain a comma or braces
47
48   major restrictions as compared to tdb:
49
50      - no explicit locking calls
51
52 */
53
54 /*
55   an individual lump of data in a result comes in this format. The
56   pointer will usually be to a UTF-8 string if the application is
57   sensible, but it can be to anything you like, including binary data
58   blobs of arbitrary size.
59 */
60 #ifndef ldb_val
61 struct ldb_val {
62         uint8_t *data;
63         size_t length;
64 };
65 #endif
66
67 /* internal ldb exploded dn structures */
68 struct ldb_dn_component {
69         char *name;
70         struct ldb_val value;
71 };
72 struct ldb_dn {
73         int comp_num;
74         struct ldb_dn_component *components;
75 };
76
77 /* these flags are used in ldd_message_element.flags fields. The
78    LDA_FLAGS_MOD_* flags are used in ldap_modify() calls to specify
79    whether attributes are being added, deleted or modified */
80 #define LDB_FLAG_MOD_MASK  0x3
81 #define LDB_FLAG_MOD_ADD     1
82 #define LDB_FLAG_MOD_REPLACE 2
83 #define LDB_FLAG_MOD_DELETE  3
84
85
86 /*
87   well known object IDs
88 */
89 #define LDB_OID_COMPARATOR_AND  "1.2.840.113556.1.4.803"
90 #define LDB_OID_COMPARATOR_OR   "1.2.840.113556.1.4.804"
91
92 /*
93   results are given back as arrays of ldb_message_element
94 */
95 struct ldb_message_element {
96         unsigned int flags;
97         const char *name;
98         unsigned int num_values;
99         struct ldb_val *values;
100 };
101
102
103 /*
104   a ldb_message represents all or part of a record. It can contain an arbitrary
105   number of elements. 
106 */
107 struct ldb_message {
108         struct ldb_dn *dn;
109         unsigned int num_elements;
110         struct ldb_message_element *elements;
111         void *private_data; /* private to the backend */
112 };
113
114 enum ldb_changetype {
115         LDB_CHANGETYPE_NONE=0,
116         LDB_CHANGETYPE_ADD,
117         LDB_CHANGETYPE_DELETE,
118         LDB_CHANGETYPE_MODIFY
119 };
120
121 /*
122   a ldif record - from ldif_read
123 */
124 struct ldb_ldif {
125         enum ldb_changetype changetype;
126         struct ldb_message *msg;
127 };
128
129 enum ldb_scope {LDB_SCOPE_DEFAULT=-1, 
130                 LDB_SCOPE_BASE=0, 
131                 LDB_SCOPE_ONELEVEL=1,
132                 LDB_SCOPE_SUBTREE=2};
133
134 struct ldb_context;
135
136 /*
137   the fuction type for the callback used in traversing the database
138 */
139 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
140
141
142 struct ldb_module;
143
144 /* debugging uses one of the following levels */
145 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR, 
146                       LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
147
148 /*
149   the user can optionally supply a debug function. The function
150   is based on the vfprintf() style of interface, but with the addition
151   of a severity level
152 */
153 struct ldb_debug_ops {
154         void (*debug)(void *context, enum ldb_debug_level level, 
155                       const char *fmt, va_list ap);
156         void *context;
157 };
158
159 #define LDB_FLG_RDONLY 1
160
161 #ifndef PRINTF_ATTRIBUTE
162 #define PRINTF_ATTRIBUTE(a,b)
163 #endif
164
165
166 /* structues for ldb_parse_tree handling code */
167 enum ldb_parse_op { LDB_OP_AND=1, LDB_OP_OR=2, LDB_OP_NOT=3,
168                     LDB_OP_EQUALITY=4, LDB_OP_SUBSTRING=5,
169                     LDB_OP_GREATER=6, LDB_OP_LESS=7, LDB_OP_PRESENT=8,
170                     LDB_OP_APPROX=9, LDB_OP_EXTENDED=10 };
171
172 struct ldb_parse_tree {
173         enum ldb_parse_op operation;
174         union {
175                 struct {
176                         struct ldb_parse_tree *child;
177                 } isnot;
178                 struct {
179                         char *attr;
180                         struct ldb_val value;
181                 } equality;
182                 struct {
183                         char *attr;
184                         int start_with_wildcard;
185                         int end_with_wildcard;
186                         struct ldb_val **chunks;
187                 } substring;
188                 struct {
189                         char *attr;
190                 } present;
191                 struct {
192                         char *attr;
193                         struct ldb_val value;
194                 } comparison;
195                 struct {
196                         char *attr;
197                         int dnAttributes;
198                         char *rule_id;
199                         struct ldb_val value;
200                 } extended;
201                 struct {
202                         unsigned int num_elements;
203                         struct ldb_parse_tree **elements;
204                 } list;
205         } u;
206 };
207
208 struct ldb_parse_tree *ldb_parse_tree(void *mem_ctx, const char *s);
209 char *ldb_filter_from_tree(void *mem_ctx, struct ldb_parse_tree *tree);
210 char *ldb_binary_encode(void *ctx, struct ldb_val val);
211
212
213 /*
214   functions for controlling attribute handling
215 */
216 typedef int (*ldb_attr_handler_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, struct ldb_val *);
217 typedef int (*ldb_attr_comparison_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, const struct ldb_val *);
218
219 struct ldb_attrib_handler {
220         const char *attr;
221
222         /* LDB_ATTR_FLAG_* */
223         unsigned flags;
224
225         /* convert from ldif to binary format */
226         ldb_attr_handler_t ldif_read_fn;
227
228         /* convert from binary to ldif format */
229         ldb_attr_handler_t ldif_write_fn;
230         
231         /* canonicalise a value, for use by indexing and dn construction */
232         ldb_attr_handler_t canonicalise_fn;
233
234         /* compare two values */
235         ldb_attr_comparison_t comparison_fn;
236 };
237
238 #define LDB_ATTR_FLAG_HIDDEN     (1<<0)
239
240 /* well-known ldap attribute syntaxes - see rfc2252 section 4.3.2 */
241 #define LDB_SYNTAX_DN                   "1.3.6.1.4.1.1466.115.121.1.12"
242 #define LDB_SYNTAX_DIRECTORY_STRING     "1.3.6.1.4.1.1466.115.121.1.15"
243 #define LDB_SYNTAX_INTEGER              "1.3.6.1.4.1.1466.115.121.1.27"
244 #define LDB_SYNTAX_OCTET_STRING         "1.3.6.1.4.1.1466.115.121.1.40"
245 #define LDB_SYNTAX_OBJECTCLASS          "LDB_SYNTAX_OBJECTCLASS"
246
247 /*
248   initialise a ldb context
249 */
250 struct ldb_context *ldb_init(void *mem_ctx);
251
252 /* 
253  connect to a database. The URL can either be one of the following forms
254    ldb://path
255    ldapi://path
256
257    flags is made up of LDB_FLG_*
258
259    the options are passed uninterpreted to the backend, and are
260    backend specific
261 */
262 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
263
264 /*
265   search the database given a LDAP-like search expression
266
267   return the number of records found, or -1 on error
268
269   use talloc_free to free the ldb_message returned
270 */
271 int ldb_search(struct ldb_context *ldb, 
272                const const struct ldb_dn *base,
273                enum ldb_scope scope,
274                const char *expression,
275                const char * const *attrs, struct ldb_message ***res);
276
277 /*
278   like ldb_search() but takes a parse tree
279 */
280 int ldb_search_bytree(struct ldb_context *ldb, 
281                       const struct ldb_dn *base,
282                       enum ldb_scope scope,
283                       struct ldb_parse_tree *tree,
284                       const char * const *attrs, struct ldb_message ***res);
285
286 /*
287   add a record to the database. Will fail if a record with the given class and key
288   already exists
289 */
290 int ldb_add(struct ldb_context *ldb, 
291             const struct ldb_message *message);
292
293 /*
294   modify the specified attributes of a record
295 */
296 int ldb_modify(struct ldb_context *ldb, 
297                const struct ldb_message *message);
298
299 /*
300   rename a record in the database
301 */
302 int ldb_rename(struct ldb_context *ldb, const struct ldb_dn *olddn, const struct ldb_dn *newdn);
303
304 /*
305   create a named lock
306 */
307 int ldb_lock(struct ldb_context *ldb, const char *lockname);
308
309 /*
310   release a named lock
311 */
312 int ldb_unlock(struct ldb_context *ldb, const char *lockname);
313
314 /*
315   delete a record from the database
316 */
317 int ldb_delete(struct ldb_context *ldb, const struct ldb_dn *dn);
318
319
320 /*
321   return extended error information from the last call
322 */
323 const char *ldb_errstring(struct ldb_context *ldb);
324
325 /*
326   casefold a string (should be UTF8, but at the moment it isn't)
327 */
328 char *ldb_casefold(void *mem_ctx, const char *s);
329 int ldb_caseless_cmp(const char *s1, const char *s2);
330
331 /*
332   ldif manipulation functions
333 */
334 int ldb_ldif_write(struct ldb_context *ldb,
335                    int (*fprintf_fn)(void *, const char *, ...), 
336                    void *private_data,
337                    const struct ldb_ldif *ldif);
338 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *);
339 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb, 
340                                int (*fgetc_fn)(void *), void *private_data);
341 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
342 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
343 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
344 char *ldb_base64_encode(void *mem_ctx, const char *buf, int len);
345 int ldb_base64_decode(char *s);
346 int ldb_attrib_add_handlers(struct ldb_context *ldb, 
347                             const struct ldb_attrib_handler *handlers, 
348                             unsigned num_handlers);
349
350 /* The following definitions come from lib/ldb/common/ldb_dn.c  */
351
352 int ldb_dn_is_special(const struct ldb_dn *dn);
353 int ldb_dn_check_special(const struct ldb_dn *dn, const char *check);
354 char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
355 struct ldb_dn *ldb_dn_new(void *mem_ctx);
356 struct ldb_dn *ldb_dn_explode(void *mem_ctx, const char *dn);
357 char *ldb_dn_linearize(void *mem_ctx, const struct ldb_dn *edn);
358 char *ldb_dn_linearize_casefold(struct ldb_context *ldb, const struct ldb_dn *edn);
359 int ldb_dn_compare_base(struct ldb_context *ldb, const struct ldb_dn *base, const struct ldb_dn *dn);
360 int ldb_dn_compare(struct ldb_context *ldb, const struct ldb_dn *edn0, const struct ldb_dn *edn1);
361 struct ldb_dn *ldb_dn_casefold(struct ldb_context *ldb, const struct ldb_dn *edn);
362 struct ldb_dn *ldb_dn_explode_casefold(struct ldb_context *ldb, const char *dn);
363 struct ldb_dn *ldb_dn_copy_partial(void *mem_ctx, const struct ldb_dn *dn, int num_el);
364 struct ldb_dn *ldb_dn_copy(void *mem_ctx, const struct ldb_dn *dn);
365 struct ldb_dn *ldb_dn_get_parent(void *mem_ctx, const struct ldb_dn *dn);
366 struct ldb_dn_component *ldb_dn_build_component(void *mem_ctx, const char *attr,
367                                                                const char *val);
368 struct ldb_dn *ldb_dn_build_child(void *mem_ctx, const char *attr,
369                                                  const char * value,
370                                                  const struct ldb_dn *base);
371 struct ldb_dn *ldb_dn_make_child(void *mem_ctx,
372                                  const struct ldb_dn_component *component,
373                                  const struct ldb_dn *base);
374 struct ldb_dn *ldb_dn_compose(void *mem_ctx, const struct ldb_dn *dn1, const struct ldb_dn *dn2);
375 struct ldb_dn *ldb_dn_string_compose(void *mem_ctx, const struct ldb_dn *base, const char *child_fmt, ...);
376 struct ldb_dn_component *ldb_dn_get_rdn(void *mem_ctx, const struct ldb_dn *dn);
377
378 /* useful functions for ldb_message structure manipulation */
379 int ldb_dn_cmp(struct ldb_context *ldb, const char *dn1, const char *dn2);
380 int ldb_attr_cmp(const char *dn1, const char *dn2);
381 char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
382
383 /* create an empty message */
384 struct ldb_message *ldb_msg_new(void *mem_ctx);
385
386 /* find an element within an message */
387 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg, 
388                                                  const char *attr_name);
389
390 /* compare two ldb_val values - return 0 on match */
391 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
392
393 /* find a value within an ldb_message_element */
394 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el, 
395                                  struct ldb_val *val);
396
397 /* add a new empty element to a ldb_message */
398 int ldb_msg_add_empty(struct ldb_context *ldb,
399                       struct ldb_message *msg, const char *attr_name, int flags);
400
401 /* add a element to a ldb_message */
402 int ldb_msg_add(struct ldb_context *ldb, 
403                 struct ldb_message *msg, 
404                 const struct ldb_message_element *el, 
405                 int flags);
406 int ldb_msg_add_value(struct ldb_context *ldb,
407                       struct ldb_message *msg, 
408                       const char *attr_name,
409                       const struct ldb_val *val);
410 int ldb_msg_add_string(struct ldb_context *ldb, struct ldb_message *msg, 
411                        const char *attr_name, const char *str);
412 int ldb_msg_add_fmt(struct ldb_context *ldb, struct ldb_message *msg, 
413                     const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(4,5);
414
415 /* compare two message elements - return 0 on match */
416 int ldb_msg_element_compare(struct ldb_message_element *el1, 
417                             struct ldb_message_element *el2);
418
419 /* find elements in a message and convert to a specific type, with
420    a give default value if not found. Assumes that elements are
421    single valued */
422 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
423 int ldb_msg_find_int(const struct ldb_message *msg, 
424                      const char *attr_name,
425                      int default_value);
426 unsigned int ldb_msg_find_uint(const struct ldb_message *msg, 
427                                const char *attr_name,
428                                unsigned int default_value);
429 int64_t ldb_msg_find_int64(const struct ldb_message *msg, 
430                            const char *attr_name,
431                            int64_t default_value);
432 uint64_t ldb_msg_find_uint64(const struct ldb_message *msg, 
433                              const char *attr_name,
434                              uint64_t default_value);
435 double ldb_msg_find_double(const struct ldb_message *msg, 
436                            const char *attr_name,
437                            double default_value);
438 const char *ldb_msg_find_string(const struct ldb_message *msg, 
439                                 const char *attr_name,
440                                 const char *default_value);
441
442 void ldb_msg_sort_elements(struct ldb_message *msg);
443
444 struct ldb_message *ldb_msg_copy(void *mem_ctx, 
445                                  const struct ldb_message *msg);
446
447 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb, 
448                                          const struct ldb_message *msg);
449
450
451 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb, 
452                                  struct ldb_message *msg1,
453                                  struct ldb_message *msg2);
454
455 struct ldb_val ldb_val_dup(void *mem_ctx, const struct ldb_val *v);
456
457 /*
458   this allows the user to set a debug function for error reporting
459 */
460 int ldb_set_debug(struct ldb_context *ldb,
461                   void (*debug)(void *context, enum ldb_debug_level level, 
462                                 const char *fmt, va_list ap),
463                   void *context);
464
465 /* this sets up debug to print messages on stderr */
466 int ldb_set_debug_stderr(struct ldb_context *ldb);
467
468 /* control backend specific opaque values */
469 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
470 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
471
472 const struct ldb_attrib_handler *ldb_attrib_handler(struct ldb_context *ldb,
473                                                     const char *attrib);
474
475 #endif