r7740: get rid of our duplicate base64 routines
[ira/wip.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 /* these flags are used in ldd_message_element.flags fields. The
68    LDA_FLAGS_MOD_* flags are used in ldap_modify() calls to specify
69    whether attributes are being added, deleted or modified */
70 #define LDB_FLAG_MOD_MASK  0x3
71 #define LDB_FLAG_MOD_ADD     1
72 #define LDB_FLAG_MOD_REPLACE 2
73 #define LDB_FLAG_MOD_DELETE  3
74
75
76 /*
77   well known object IDs
78 */
79 #define LDB_OID_COMPARATOR_AND  "1.2.840.113556.1.4.803"
80 #define LDB_OID_COMPARATOR_OR   "1.2.840.113556.1.4.804"
81
82 /*
83   results are given back as arrays of ldb_message_element
84 */
85 struct ldb_message_element {
86         unsigned int flags;
87         const char *name;
88         unsigned int num_values;
89         struct ldb_val *values;
90 };
91
92
93 /*
94   a ldb_message represents all or part of a record. It can contain an arbitrary
95   number of elements. 
96 */
97 struct ldb_message {
98         char *dn;
99         unsigned int num_elements;
100         struct ldb_message_element *elements;
101         void *private_data; /* private to the backend */
102 };
103
104 enum ldb_changetype {
105         LDB_CHANGETYPE_NONE=0,
106         LDB_CHANGETYPE_ADD,
107         LDB_CHANGETYPE_DELETE,
108         LDB_CHANGETYPE_MODIFY
109 };
110
111 /*
112   a ldif record - from ldif_read
113 */
114 struct ldb_ldif {
115         enum ldb_changetype changetype;
116         struct ldb_message *msg;
117 };
118
119 enum ldb_scope {LDB_SCOPE_DEFAULT=-1, 
120                 LDB_SCOPE_BASE=0, 
121                 LDB_SCOPE_ONELEVEL=1,
122                 LDB_SCOPE_SUBTREE=2};
123
124 struct ldb_context;
125
126 /*
127   the fuction type for the callback used in traversing the database
128 */
129 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
130
131
132 struct ldb_module;
133
134 /* debugging uses one of the following levels */
135 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR, 
136                       LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
137
138 /*
139   the user can optionally supply a debug function. The function
140   is based on the vfprintf() style of interface, but with the addition
141   of a severity level
142 */
143 struct ldb_debug_ops {
144         void (*debug)(void *context, enum ldb_debug_level level, 
145                       const char *fmt, va_list ap);
146         void *context;
147 };
148
149 #define LDB_FLG_RDONLY 1
150
151 #ifndef PRINTF_ATTRIBUTE
152 #define PRINTF_ATTRIBUTE(a,b)
153 #endif
154
155
156 /* structues for ldb_parse_tree handling code */
157 enum ldb_parse_op {LDB_OP_SIMPLE=1, LDB_OP_EXTENDED=2, 
158                    LDB_OP_AND='&', LDB_OP_OR='|', LDB_OP_NOT='!'};
159
160 struct ldb_parse_tree {
161         enum ldb_parse_op operation;
162         union {
163                 struct {
164                         char *attr;
165                         struct ldb_val value;
166                 } simple;
167                 struct {
168                         char *attr;
169                         int dnAttributes;
170                         char *rule_id;
171                         struct ldb_val value;
172                 } extended;
173                 struct {
174                         unsigned int num_elements;
175                         struct ldb_parse_tree **elements;
176                 } list;
177                 struct {
178                         struct ldb_parse_tree *child;
179                 } not;
180         } u;
181 };
182
183 struct ldb_parse_tree *ldb_parse_tree(void *mem_ctx, const char *s);
184 char *ldb_filter_from_tree(void *mem_ctx, struct ldb_parse_tree *tree);
185 char *ldb_binary_encode(void *ctx, struct ldb_val val);
186
187 /*
188   initialise a ldb context
189 */
190 struct ldb_context *ldb_init(void *mem_ctx);
191
192 /* 
193  connect to a database. The URL can either be one of the following forms
194    ldb://path
195    ldapi://path
196
197    flags is made up of LDB_FLG_*
198
199    the options are passed uninterpreted to the backend, and are
200    backend specific
201 */
202 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
203
204 /*
205   search the database given a LDAP-like search expression
206
207   return the number of records found, or -1 on error
208
209   use talloc_free to free the ldb_message returned
210 */
211 int ldb_search(struct ldb_context *ldb, 
212                const char *base,
213                enum ldb_scope scope,
214                const char *expression,
215                const char * const *attrs, struct ldb_message ***res);
216
217 /*
218   like ldb_search() but takes a parse tree
219 */
220 int ldb_search_bytree(struct ldb_context *ldb, 
221                       const char *base,
222                       enum ldb_scope scope,
223                       struct ldb_parse_tree *tree,
224                       const char * const *attrs, struct ldb_message ***res);
225
226 /*
227   add a record to the database. Will fail if a record with the given class and key
228   already exists
229 */
230 int ldb_add(struct ldb_context *ldb, 
231             const struct ldb_message *message);
232
233 /*
234   modify the specified attributes of a record
235 */
236 int ldb_modify(struct ldb_context *ldb, 
237                const struct ldb_message *message);
238
239 /*
240   rename a record in the database
241 */
242 int ldb_rename(struct ldb_context *ldb, const char *olddn, const char *newdn);
243
244 /*
245   delete a record from the database
246 */
247 int ldb_delete(struct ldb_context *ldb, const char *dn);
248
249
250 /*
251   return extended error information from the last call
252 */
253 const char *ldb_errstring(struct ldb_context *ldb);
254
255 /*
256   casefold a string (should be UTF8, but at the moment it isn't)
257 */
258 char *ldb_casefold(void *mem_ctx, const char *s);
259
260 /*
261   ldif manipulation functions
262 */
263 int ldb_ldif_write(struct ldb_context *ldb,
264                    int (*fprintf_fn)(void *, const char *, ...), 
265                    void *private_data,
266                    const struct ldb_ldif *ldif);
267 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *);
268 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb, 
269                                int (*fgetc_fn)(void *), void *private_data);
270 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
271 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char *s);
272 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
273 char *ldb_base64_encode(void *mem_ctx, const char *buf, int len);
274 int ldb_base64_decode(char *s);
275
276
277 /* useful functions for ldb_message structure manipulation */
278
279 int ldb_dn_cmp(const char *dn1, const char *dn2);
280 int ldb_attr_cmp(const char *dn1, const char *dn2);
281
282 /* case-fold a DN */
283 char *ldb_dn_fold(void * mem_ctx,
284                   const char * dn,
285                   void * user_data,
286                   int (* case_fold_attr_fn)(void * user_data, char * attr));
287
288 /* create an empty message */
289 struct ldb_message *ldb_msg_new(void *mem_ctx);
290
291 /* find an element within an message */
292 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg, 
293                                                  const char *attr_name);
294
295 /* compare two ldb_val values - return 0 on match */
296 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
297
298 /* find a value within an ldb_message_element */
299 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el, 
300                                  struct ldb_val *val);
301
302 /* add a new empty element to a ldb_message */
303 int ldb_msg_add_empty(struct ldb_context *ldb,
304                       struct ldb_message *msg, const char *attr_name, int flags);
305
306 /* add a element to a ldb_message */
307 int ldb_msg_add(struct ldb_context *ldb, 
308                 struct ldb_message *msg, 
309                 const struct ldb_message_element *el, 
310                 int flags);
311 int ldb_msg_add_value(struct ldb_context *ldb,
312                       struct ldb_message *msg, 
313                       const char *attr_name,
314                       const struct ldb_val *val);
315 int ldb_msg_add_string(struct ldb_context *ldb, struct ldb_message *msg, 
316                        const char *attr_name, const char *str);
317 int ldb_msg_add_fmt(struct ldb_context *ldb, struct ldb_message *msg, 
318                     const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(4,5);
319
320 /* compare two message elements - return 0 on match */
321 int ldb_msg_element_compare(struct ldb_message_element *el1, 
322                             struct ldb_message_element *el2);
323
324 /* find elements in a message and convert to a specific type, with
325    a give default value if not found. Assumes that elements are
326    single valued */
327 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
328 int ldb_msg_find_int(const struct ldb_message *msg, 
329                      const char *attr_name,
330                      int default_value);
331 unsigned int ldb_msg_find_uint(const struct ldb_message *msg, 
332                                const char *attr_name,
333                                unsigned int default_value);
334 int64_t ldb_msg_find_int64(const struct ldb_message *msg, 
335                            const char *attr_name,
336                            int64_t default_value);
337 uint64_t ldb_msg_find_uint64(const struct ldb_message *msg, 
338                              const char *attr_name,
339                              uint64_t default_value);
340 double ldb_msg_find_double(const struct ldb_message *msg, 
341                            const char *attr_name,
342                            double default_value);
343 const char *ldb_msg_find_string(const struct ldb_message *msg, 
344                                 const char *attr_name,
345                                 const char *default_value);
346
347 void ldb_msg_sort_elements(struct ldb_message *msg);
348
349 void ldb_msg_free(struct ldb_context *ldb, struct ldb_message *msg);
350
351 struct ldb_message *ldb_msg_copy(struct ldb_context *ldb, 
352                                  const struct ldb_message *msg);
353
354 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb, 
355                                          const struct ldb_message *msg);
356
357
358 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb, 
359                                  struct ldb_message *msg1,
360                                  struct ldb_message *msg2);
361
362 struct ldb_val ldb_val_dup(void *mem_ctx, const struct ldb_val *v);
363
364 /*
365   this allows the user to set a debug function for error reporting
366 */
367 int ldb_set_debug(struct ldb_context *ldb,
368                   void (*debug)(void *context, enum ldb_debug_level level, 
369                                 const char *fmt, va_list ap),
370                   void *context);
371
372 /* this sets up debug to print messages on stderr */
373 int ldb_set_debug_stderr(struct ldb_context *ldb);
374
375 #endif