r9621: Bunch of bug fixes. Add 'format' option to samba3dump (text,summary,ldif)
[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 /* structures for ldb_parse_tree handling code */
166 enum ldb_parse_op { LDB_OP_AND=1, LDB_OP_OR=2, LDB_OP_NOT=3,
167                     LDB_OP_EQUALITY=4, LDB_OP_SUBSTRING=5,
168                     LDB_OP_GREATER=6, LDB_OP_LESS=7, LDB_OP_PRESENT=8,
169                     LDB_OP_APPROX=9, LDB_OP_EXTENDED=10 };
170
171 struct ldb_parse_tree {
172         enum ldb_parse_op operation;
173         union {
174                 struct {
175                         struct ldb_parse_tree *child;
176                 } isnot;
177                 struct {
178                         char *attr;
179                         struct ldb_val value;
180                 } equality;
181                 struct {
182                         char *attr;
183                         int start_with_wildcard;
184                         int end_with_wildcard;
185                         struct ldb_val **chunks;
186                 } substring;
187                 struct {
188                         char *attr;
189                 } present;
190                 struct {
191                         char *attr;
192                         struct ldb_val value;
193                 } comparison;
194                 struct {
195                         char *attr;
196                         int dnAttributes;
197                         char *rule_id;
198                         struct ldb_val value;
199                 } extended;
200                 struct {
201                         unsigned int num_elements;
202                         struct ldb_parse_tree **elements;
203                 } list;
204         } u;
205 };
206
207 struct ldb_parse_tree *ldb_parse_tree(void *mem_ctx, const char *s);
208 char *ldb_filter_from_tree(void *mem_ctx, struct ldb_parse_tree *tree);
209 char *ldb_binary_encode(void *ctx, struct ldb_val val);
210
211
212 /*
213   functions for controlling attribute handling
214 */
215 typedef int (*ldb_attr_handler_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, struct ldb_val *);
216 typedef int (*ldb_attr_comparison_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, const struct ldb_val *);
217
218 struct ldb_attrib_handler {
219         const char *attr;
220
221         /* LDB_ATTR_FLAG_* */
222         unsigned flags;
223
224         /* convert from ldif to binary format */
225         ldb_attr_handler_t ldif_read_fn;
226
227         /* convert from binary to ldif format */
228         ldb_attr_handler_t ldif_write_fn;
229         
230         /* canonicalise a value, for use by indexing and dn construction */
231         ldb_attr_handler_t canonicalise_fn;
232
233         /* compare two values */
234         ldb_attr_comparison_t comparison_fn;
235 };
236
237 #define LDB_ATTR_FLAG_HIDDEN     (1<<0)
238
239 /* well-known ldap attribute syntaxes - see rfc2252 section 4.3.2 */
240 #define LDB_SYNTAX_DN                   "1.3.6.1.4.1.1466.115.121.1.12"
241 #define LDB_SYNTAX_DIRECTORY_STRING     "1.3.6.1.4.1.1466.115.121.1.15"
242 #define LDB_SYNTAX_INTEGER              "1.3.6.1.4.1.1466.115.121.1.27"
243 #define LDB_SYNTAX_OCTET_STRING         "1.3.6.1.4.1.1466.115.121.1.40"
244 #define LDB_SYNTAX_OBJECTCLASS          "LDB_SYNTAX_OBJECTCLASS"
245
246 /*
247   initialise a ldb context
248 */
249 struct ldb_context *ldb_init(void *mem_ctx);
250
251 /* 
252  connect to a database. The URL can either be one of the following forms
253    ldb://path
254    ldapi://path
255
256    flags is made up of LDB_FLG_*
257
258    the options are passed uninterpreted to the backend, and are
259    backend specific
260 */
261 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
262
263 /*
264   search the database given a LDAP-like search expression
265
266   return the number of records found, or -1 on error
267
268   use talloc_free to free the ldb_message returned
269 */
270 int ldb_search(struct ldb_context *ldb, 
271                const const struct ldb_dn *base,
272                enum ldb_scope scope,
273                const char *expression,
274                const char * const *attrs, struct ldb_message ***res);
275
276 /*
277   like ldb_search() but takes a parse tree
278 */
279 int ldb_search_bytree(struct ldb_context *ldb, 
280                       const struct ldb_dn *base,
281                       enum ldb_scope scope,
282                       struct ldb_parse_tree *tree,
283                       const char * const *attrs, struct ldb_message ***res);
284
285 /*
286   add a record to the database. Will fail if a record with the given class and key
287   already exists
288 */
289 int ldb_add(struct ldb_context *ldb, 
290             const struct ldb_message *message);
291
292 /*
293   modify the specified attributes of a record
294 */
295 int ldb_modify(struct ldb_context *ldb, 
296                const struct ldb_message *message);
297
298 /*
299   rename a record in the database
300 */
301 int ldb_rename(struct ldb_context *ldb, const struct ldb_dn *olddn, const struct ldb_dn *newdn);
302
303 /*
304   create a named lock
305 */
306 int ldb_lock(struct ldb_context *ldb, const char *lockname);
307
308 /*
309   release a named lock
310 */
311 int ldb_unlock(struct ldb_context *ldb, const char *lockname);
312
313 /*
314   delete a record from the database
315 */
316 int ldb_delete(struct ldb_context *ldb, const struct ldb_dn *dn);
317
318
319 /*
320   return extended error information from the last call
321 */
322 const char *ldb_errstring(struct ldb_context *ldb);
323
324 /*
325   casefold a string (should be UTF8, but at the moment it isn't)
326 */
327 char *ldb_casefold(void *mem_ctx, const char *s);
328 int ldb_caseless_cmp(const char *s1, const char *s2);
329
330 /*
331   ldif manipulation functions
332 */
333 int ldb_ldif_write(struct ldb_context *ldb,
334                    int (*fprintf_fn)(void *, const char *, ...), 
335                    void *private_data,
336                    const struct ldb_ldif *ldif);
337 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *);
338 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb, 
339                                int (*fgetc_fn)(void *), void *private_data);
340 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
341 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
342 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
343 char *ldb_base64_encode(void *mem_ctx, const char *buf, int len);
344 int ldb_base64_decode(char *s);
345 int ldb_attrib_add_handlers(struct ldb_context *ldb, 
346                             const struct ldb_attrib_handler *handlers, 
347                             unsigned num_handlers);
348
349 /* The following definitions come from lib/ldb/common/ldb_dn.c  */
350
351 int ldb_dn_is_special(const struct ldb_dn *dn);
352 int ldb_dn_check_special(const struct ldb_dn *dn, const char *check);
353 char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
354 struct ldb_dn *ldb_dn_new(void *mem_ctx);
355 struct ldb_dn *ldb_dn_explode(void *mem_ctx, const char *dn);
356 char *ldb_dn_linearize(void *mem_ctx, const struct ldb_dn *edn);
357 char *ldb_dn_linearize_casefold(struct ldb_context *ldb, const struct ldb_dn *edn);
358 int ldb_dn_compare_base(struct ldb_context *ldb, const struct ldb_dn *base, const struct ldb_dn *dn);
359 int ldb_dn_compare(struct ldb_context *ldb, const struct ldb_dn *edn0, const struct ldb_dn *edn1);
360 struct ldb_dn *ldb_dn_casefold(struct ldb_context *ldb, const struct ldb_dn *edn);
361 struct ldb_dn *ldb_dn_explode_casefold(struct ldb_context *ldb, const char *dn);
362 struct ldb_dn *ldb_dn_copy_partial(void *mem_ctx, const struct ldb_dn *dn, int num_el);
363 struct ldb_dn *ldb_dn_copy(void *mem_ctx, const struct ldb_dn *dn);
364 struct ldb_dn *ldb_dn_get_parent(void *mem_ctx, const struct ldb_dn *dn);
365 struct ldb_dn_component *ldb_dn_build_component(void *mem_ctx, const char *attr,
366                                                                const char *val);
367 struct ldb_dn *ldb_dn_build_child(void *mem_ctx, const char *attr,
368                                                  const char * value,
369                                                  const struct ldb_dn *base);
370 struct ldb_dn *ldb_dn_make_child(void *mem_ctx,
371                                  const struct ldb_dn_component *component,
372                                  const struct ldb_dn *base);
373 struct ldb_dn *ldb_dn_compose(void *mem_ctx, const struct ldb_dn *dn1, const struct ldb_dn *dn2);
374 struct ldb_dn *ldb_dn_string_compose(void *mem_ctx, const struct ldb_dn *base, const char *child_fmt, ...);
375 struct ldb_dn_component *ldb_dn_get_rdn(void *mem_ctx, const struct ldb_dn *dn);
376
377 /* useful functions for ldb_message structure manipulation */
378 int ldb_dn_cmp(struct ldb_context *ldb, const char *dn1, const char *dn2);
379 int ldb_attr_cmp(const char *dn1, const char *dn2);
380 char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
381
382 /* create an empty message */
383 struct ldb_message *ldb_msg_new(void *mem_ctx);
384
385 /* find an element within an message */
386 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg, 
387                                                  const char *attr_name);
388
389 /* compare two ldb_val values - return 0 on match */
390 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
391
392 /* find a value within an ldb_message_element */
393 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el, 
394                                  struct ldb_val *val);
395
396 /* add a new empty element to a ldb_message */
397 int ldb_msg_add_empty(struct ldb_context *ldb,
398                       struct ldb_message *msg, const char *attr_name, int flags);
399
400 /* add a element to a ldb_message */
401 int ldb_msg_add(struct ldb_context *ldb, 
402                 struct ldb_message *msg, 
403                 const struct ldb_message_element *el, 
404                 int flags);
405 int ldb_msg_add_value(struct ldb_context *ldb,
406                       struct ldb_message *msg, 
407                       const char *attr_name,
408                       const struct ldb_val *val);
409 int ldb_msg_add_string(struct ldb_context *ldb, struct ldb_message *msg, 
410                        const char *attr_name, const char *str);
411 int ldb_msg_add_fmt(struct ldb_context *ldb, struct ldb_message *msg, 
412                     const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(4,5);
413
414 /* compare two message elements - return 0 on match */
415 int ldb_msg_element_compare(struct ldb_message_element *el1, 
416                             struct ldb_message_element *el2);
417
418 /* find elements in a message and convert to a specific type, with
419    a give default value if not found. Assumes that elements are
420    single valued */
421 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
422 int ldb_msg_find_int(const struct ldb_message *msg, 
423                      const char *attr_name,
424                      int default_value);
425 unsigned int ldb_msg_find_uint(const struct ldb_message *msg, 
426                                const char *attr_name,
427                                unsigned int default_value);
428 int64_t ldb_msg_find_int64(const struct ldb_message *msg, 
429                            const char *attr_name,
430                            int64_t default_value);
431 uint64_t ldb_msg_find_uint64(const struct ldb_message *msg, 
432                              const char *attr_name,
433                              uint64_t default_value);
434 double ldb_msg_find_double(const struct ldb_message *msg, 
435                            const char *attr_name,
436                            double default_value);
437 const char *ldb_msg_find_string(const struct ldb_message *msg, 
438                                 const char *attr_name,
439                                 const char *default_value);
440
441 void ldb_msg_sort_elements(struct ldb_message *msg);
442
443 struct ldb_message *ldb_msg_copy(void *mem_ctx, 
444                                  const struct ldb_message *msg);
445
446 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb, 
447                                          const struct ldb_message *msg);
448
449
450 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb, 
451                                  struct ldb_message *msg1,
452                                  struct ldb_message *msg2);
453
454 struct ldb_val ldb_val_dup(void *mem_ctx, const struct ldb_val *v);
455
456 /*
457   this allows the user to set a debug function for error reporting
458 */
459 int ldb_set_debug(struct ldb_context *ldb,
460                   void (*debug)(void *context, enum ldb_debug_level level, 
461                                 const char *fmt, va_list ap),
462                   void *context);
463
464 /* this sets up debug to print messages on stderr */
465 int ldb_set_debug_stderr(struct ldb_context *ldb);
466
467 /* control backend specific opaque values */
468 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
469 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
470
471 const struct ldb_attrib_handler *ldb_attrib_handler(struct ldb_context *ldb,
472                                                     const char *attrib);
473
474 #endif