r2792: got rid of talloc_ldb_alloc() and instead created talloc_realloc_fn(),
[bbaumbach/samba-autobuild/.git] / source4 / lib / ldb / include / ldb.h
1 /* 
2    ldb database library
3
4    Copyright (C) Andrew Tridgell  2004
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 2 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, write to the Free Software
22    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
23 */
24
25 /*
26  *  Name: ldb
27  *
28  *  Component: ldb header
29  *
30  *  Description: defines for base ldb API
31  *
32  *  Author: Andrew Tridgell
33  */
34
35 #ifndef _LDB_H_
36 #define _LDB_H_ 1
37
38 /*
39   major restrictions as compared to normal LDAP:
40
41      - no async calls.
42      - each record must have a unique key field
43      - the key must be representable as a NULL terminated C string and may not 
44        contain a comma or braces
45
46   major restrictions as compared to tdb:
47
48      - no explicit locking calls
49
50 */
51
52 /*
53   an individual lump of data in a result comes in this format. The
54   pointer will usually be to a UTF-8 string if the application is
55   sensible, but it can be to anything you like, including binary data
56   blobs of arbitrary size.
57 */
58 struct ldb_val {
59         unsigned int length;
60         void *data;
61 };
62
63 /* these flags are used in ldd_message_element.flags fields. The
64    LDA_FLAGS_MOD_* flags are used in ldap_modify() calls to specify
65    whether attributes are being added, deleted or modified */
66 #define LDB_FLAG_MOD_MASK  0x3
67 #define LDB_FLAG_MOD_ADD     1
68 #define LDB_FLAG_MOD_REPLACE 2
69 #define LDB_FLAG_MOD_DELETE  3
70
71
72 /*
73   results are given back as arrays of ldb_message_element
74 */
75 struct ldb_message_element {
76         unsigned int flags;
77         char *name;
78         unsigned int num_values;
79         struct ldb_val *values;
80 };
81
82
83 /*
84   a ldb_message represents all or part of a record. It can contain an arbitrary
85   number of elements. 
86 */
87 struct ldb_message {
88         char *dn;
89         unsigned int num_elements;
90         struct ldb_message_element *elements;
91         void *private_data; /* private to the backend */
92 };
93
94 enum ldb_changetype {
95         LDB_CHANGETYPE_NONE=0,
96         LDB_CHANGETYPE_ADD,
97         LDB_CHANGETYPE_DELETE,
98         LDB_CHANGETYPE_MODIFY
99 };
100
101 /*
102   a ldif record - from ldif_read
103 */
104 struct ldb_ldif {
105         enum ldb_changetype changetype;
106         struct ldb_message msg;
107 };
108
109 enum ldb_scope {LDB_SCOPE_DEFAULT=-1, 
110                 LDB_SCOPE_BASE=0, 
111                 LDB_SCOPE_ONELEVEL=1,
112                 LDB_SCOPE_SUBTREE=2};
113
114 struct ldb_context;
115
116 /*
117   the fuction type for the callback used in traversing the database
118 */
119 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
120
121
122 /* 
123    these function pointers define the operations that a ldb backend must perform
124    they correspond exactly to the ldb_*() interface 
125 */
126 struct ldb_backend_ops {
127         int (*close)(struct ldb_context *);
128         int (*search)(struct ldb_context *, const char *, enum ldb_scope,
129                       const char *, const char * const [], struct ldb_message ***);
130         int (*search_free)(struct ldb_context *, struct ldb_message **);
131         int (*add_record)(struct ldb_context *, const struct ldb_message *);
132         int (*modify_record)(struct ldb_context *, const struct ldb_message *);
133         int (*delete_record)(struct ldb_context *, const char *);
134         const char * (*errstring)(struct ldb_context *);
135
136         /* this is called when the alloc ops changes to ensure we 
137            don't have any old allocated data in the context */
138         void (*cache_free)(struct ldb_context *);
139 };
140
141
142 /*
143   the user can optionally supply a allocator function. It is presumed
144   it will act like a modern realloc(), with a context ptr to allow
145   for pool allocators
146 */
147 struct ldb_alloc_ops {
148         void *(*alloc)(const void *context, void *ptr, size_t size);
149         void *context;
150 };
151
152 /* debugging uses one of the following levels */
153 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR, 
154                       LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
155
156 /*
157   the user can optionally supply a debug function. The function
158   is based on the vfprintf() style of interface, but with the addition
159   of a severity level
160 */
161 struct ldb_debug_ops {
162         void (*debug)(void *context, enum ldb_debug_level level, 
163                       const char *fmt, va_list ap);
164         void *context;
165 };
166
167
168 /*
169   every ldb connection is started by establishing a ldb_context
170 */
171 struct ldb_context {
172         /* a private pointer for the backend to use */
173         void *private_data;
174
175         /* the operations provided by the backend */
176         const struct ldb_backend_ops *ops;
177
178         /* memory allocation info */
179         struct ldb_alloc_ops alloc_ops;
180
181         /* memory allocation info */
182         struct ldb_debug_ops debug_ops;
183 };
184
185
186 #define LDB_FLG_RDONLY 1
187
188 /* 
189  connect to a database. The URL can either be one of the following forms
190    ldb://path
191    ldapi://path
192
193    flags is made up of LDB_FLG_*
194
195    the options are passed uninterpreted to the backend, and are
196    backend specific
197 */
198 struct ldb_context *ldb_connect(const char *url, unsigned int flags,
199                                 const char *options[]);
200
201 /*
202   close the connection to the database
203 */
204 int ldb_close(struct ldb_context *ldb);
205
206
207 /*
208   search the database given a LDAP-like search expression
209
210   return the number of records found, or -1 on error
211 */
212 int ldb_search(struct ldb_context *ldb, 
213                const char *base,
214                enum ldb_scope scope,
215                const char *expression,
216                const char * const *attrs, struct ldb_message ***res);
217
218 /* 
219    free a set of messages returned by ldb_search
220 */
221 int ldb_search_free(struct ldb_context *ldb, struct ldb_message **msgs);
222
223
224 /*
225   add a record to the database. Will fail if a record with the given class and key
226   already exists
227 */
228 int ldb_add(struct ldb_context *ldb, 
229             const struct ldb_message *message);
230
231 /*
232   modify the specified attributes of a record
233 */
234 int ldb_modify(struct ldb_context *ldb, 
235                const struct ldb_message *message);
236
237 /*
238   delete a record from the database
239 */
240 int ldb_delete(struct ldb_context *ldb, const char *dn);
241
242
243 /*
244   return extended error information from the last call
245 */
246 const char *ldb_errstring(struct ldb_context *ldb);
247
248 /*
249   casefold a string (should be UTF8, but at the moment it isn't)
250 */
251 char *ldb_casefold(struct ldb_context *ldb, const char *s);
252
253 /*
254   ldif manipulation functions
255 */
256 int ldb_ldif_write(struct ldb_context *ldb,
257                    int (*fprintf_fn)(void *, const char *, ...), 
258                    void *private_data,
259                    const struct ldb_ldif *ldif);
260 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *);
261 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb, 
262                                int (*fgetc_fn)(void *), void *private_data);
263 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
264 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char *s);
265 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
266
267
268 /* useful functions for ldb_message structure manipulation */
269
270 /* find an element within an message */
271 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg, 
272                                                  const char *attr_name);
273
274 /* compare two ldb_val values - return 0 on match */
275 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
276
277 /* find a value within an ldb_message_element */
278 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el, 
279                                  struct ldb_val *val);
280
281 /* add a new empty element to a ldb_message */
282 int ldb_msg_add_empty(struct ldb_context *ldb,
283                       struct ldb_message *msg, const char *attr_name, int flags);
284
285 /* add a element to a ldb_message */
286 int ldb_msg_add(struct ldb_context *ldb, 
287                 struct ldb_message *msg, 
288                 const struct ldb_message_element *el, 
289                 int flags);
290
291 /* compare two message elements - return 0 on match */
292 int ldb_msg_element_compare(struct ldb_message_element *el1, 
293                             struct ldb_message_element *el2);
294
295 /* find elements in a message and convert to a specific type, with
296    a give default value if not found. Assumes that elements are
297    single valued */
298 int ldb_msg_find_int(const struct ldb_message *msg, 
299                      const char *attr_name,
300                      int default_value);
301 unsigned int ldb_msg_find_uint(const struct ldb_message *msg, 
302                                const char *attr_name,
303                                unsigned int default_value);
304 double ldb_msg_find_double(const struct ldb_message *msg, 
305                            const char *attr_name,
306                            double default_value);
307 const char *ldb_msg_find_string(const struct ldb_message *msg, 
308                                 const char *attr_name,
309                                 const char *default_value);
310
311
312 /*
313   this allows the user to choose their own allocation function
314   the allocation function should behave like a modern realloc() 
315   function, which means that:
316      malloc(size)       == alloc(context, NULL, size)
317      free(ptr)          == alloc(context, ptr, 0)
318      realloc(ptr, size) == alloc(context, ptr, size)
319   The context argument is provided to allow for pool based allocators,
320   which often take a context argument
321 */
322 int ldb_set_alloc(struct ldb_context *ldb,
323                   void *(*alloc)(const void *context, void *ptr, size_t size),
324                   void *context);
325
326 /*
327   this allows the user to set a debug function for error reporting
328 */
329 int ldb_set_debug(struct ldb_context *ldb,
330                   void (*debug)(void *context, enum ldb_debug_level level, 
331                                 const char *fmt, va_list ap),
332                   void *context);
333
334 /* this sets up debug to print messages on stderr */
335 int ldb_set_debug_stderr(struct ldb_context *ldb);
336
337
338 /* these are used as type safe versions of the ldb allocation functions */
339 #define ldb_malloc_p(ldb, type) (type *)ldb_malloc(ldb, sizeof(type))
340 #define ldb_malloc_array_p(ldb, type, count) (type *)ldb_realloc_array(ldb, NULL, sizeof(type), count)
341 #define ldb_realloc_p(ldb, p, type, count) (type *)ldb_realloc_array(ldb, p, sizeof(type), count)
342
343 #endif