4 Copyright (C) Andrew Tridgell 2004
6 ** NOTE! The following LGPL license applies to the ldb
7 ** library. This does NOT imply that all of Samba is released
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.
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.
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
28 * Component: ldb header
30 * Description: defines for base ldb API
32 * Author: Andrew Tridgell
39 major restrictions as compared to normal LDAP:
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
46 major restrictions as compared to tdb:
48 - no explicit locking calls
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.
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
73 results are given back as arrays of ldb_message_element
75 struct ldb_message_element {
78 unsigned int num_values;
79 struct ldb_val *values;
84 a ldb_message represents all or part of a record. It can contain an arbitrary
89 unsigned int num_elements;
90 struct ldb_message_element *elements;
91 void *private_data; /* private to the backend */
95 LDB_CHANGETYPE_NONE=0,
97 LDB_CHANGETYPE_DELETE,
102 a ldif record - from ldif_read
105 enum ldb_changetype changetype;
106 struct ldb_message msg;
109 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
111 LDB_SCOPE_ONELEVEL=1,
112 LDB_SCOPE_SUBTREE=2};
117 the fuction type for the callback used in traversing the database
119 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
123 these function pointers define the operations that a ldb backend must perform
124 they correspond exactly to the ldb_*() interface
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 *);
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 *);
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
147 struct ldb_alloc_ops {
148 void *(*alloc)(void *context, void *ptr, size_t size);
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};
157 the user can optionally supply a debug function. The function
158 is based on the vfprintf() style of interface, but with the addition
161 struct ldb_debug_ops {
162 void (*debug)(void *context, enum ldb_debug_level level,
163 const char *fmt, va_list ap);
169 every ldb connection is started by establishing a ldb_context
172 /* a private pointer for the backend to use */
175 /* the operations provided by the backend */
176 const struct ldb_backend_ops *ops;
178 /* memory allocation info */
179 struct ldb_alloc_ops alloc_ops;
181 /* memory allocation info */
182 struct ldb_debug_ops debug_ops;
186 #define LDB_FLG_RDONLY 1
189 connect to a database. The URL can either be one of the following forms
193 flags is made up of LDB_FLG_*
195 the options are passed uninterpreted to the backend, and are
198 struct ldb_context *ldb_connect(const char *url, unsigned int flags,
199 const char *options[]);
202 close the connection to the database
204 int ldb_close(struct ldb_context *ldb);
208 search the database given a LDAP-like search expression
210 return the number of records found, or -1 on error
212 int ldb_search(struct ldb_context *ldb,
214 enum ldb_scope scope,
215 const char *expression,
216 const char * const *attrs, struct ldb_message ***res);
219 free a set of messages returned by ldb_search
221 int ldb_search_free(struct ldb_context *ldb, struct ldb_message **msgs);
225 add a record to the database. Will fail if a record with the given class and key
228 int ldb_add(struct ldb_context *ldb,
229 const struct ldb_message *message);
232 modify the specified attributes of a record
234 int ldb_modify(struct ldb_context *ldb,
235 const struct ldb_message *message);
238 delete a record from the database
240 int ldb_delete(struct ldb_context *ldb, const char *dn);
244 return extended error information from the last call
246 const char *ldb_errstring(struct ldb_context *ldb);
249 casefold a string (should be UTF8, but at the moment it isn't)
251 char *ldb_casefold(struct ldb_context *ldb, const char *s);
254 ldif manipulation functions
256 int ldb_ldif_write(struct ldb_context *ldb,
257 int (*fprintf_fn)(void *, const char *, ...),
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);
268 /* useful functions for ldb_message structure manipulation */
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);
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);
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);
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);
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,
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);
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
298 int ldb_msg_find_int(const struct ldb_message *msg,
299 const char *attr_name,
301 unsigned int ldb_msg_find_uint(const struct ldb_message *msg,
302 const char *attr_name,
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);
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
322 int ldb_set_alloc(struct ldb_context *ldb,
323 void *(*alloc)(void *context, void *ptr, size_t size),
327 this allows the user to set a debug function for error reporting
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),
334 /* this sets up debug to print messages on stderr */
335 int ldb_set_debug_stderr(struct ldb_context *ldb);
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)