4 Copyright (C) Andrew Tridgell 2004
5 Copyright (C) Stefan Metzmacher 2004
7 ** NOTE! The following LGPL license applies to the ldb
8 ** library. This does NOT imply that all of Samba is released
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.
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.
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
29 * Component: ldb header
31 * Description: defines for base ldb API
33 * Author: Andrew Tridgell
34 * Author: Stefan Metzmacher
41 major restrictions as compared to normal LDAP:
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
48 major restrictions as compared to tdb:
50 - no explicit locking calls
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.
65 /* these flags are used in ldd_message_element.flags fields. The
66 LDA_FLAGS_MOD_* flags are used in ldap_modify() calls to specify
67 whether attributes are being added, deleted or modified */
68 #define LDB_FLAG_MOD_MASK 0x3
69 #define LDB_FLAG_MOD_ADD 1
70 #define LDB_FLAG_MOD_REPLACE 2
71 #define LDB_FLAG_MOD_DELETE 3
75 results are given back as arrays of ldb_message_element
77 struct ldb_message_element {
80 unsigned int num_values;
81 struct ldb_val *values;
86 a ldb_message represents all or part of a record. It can contain an arbitrary
91 unsigned int num_elements;
92 struct ldb_message_element *elements;
93 void *private_data; /* private to the backend */
97 LDB_CHANGETYPE_NONE=0,
99 LDB_CHANGETYPE_DELETE,
100 LDB_CHANGETYPE_MODIFY
104 a ldif record - from ldif_read
107 enum ldb_changetype changetype;
108 struct ldb_message msg;
111 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
113 LDB_SCOPE_ONELEVEL=1,
114 LDB_SCOPE_SUBTREE=2};
119 the fuction type for the callback used in traversing the database
121 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
127 the user can optionally supply a allocator function. It is presumed
128 it will act like a modern realloc(), with a context ptr to allow
131 struct ldb_alloc_ops {
132 void *(*alloc)(const void *context, void *ptr, size_t size);
136 /* debugging uses one of the following levels */
137 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR,
138 LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
141 the user can optionally supply a debug function. The function
142 is based on the vfprintf() style of interface, but with the addition
145 struct ldb_debug_ops {
146 void (*debug)(void *context, enum ldb_debug_level level,
147 const char *fmt, va_list ap);
151 #define LDB_FLG_RDONLY 1
154 connect to a database. The URL can either be one of the following forms
158 flags is made up of LDB_FLG_*
160 the options are passed uninterpreted to the backend, and are
163 struct ldb_context *ldb_connect(const char *url, unsigned int flags,
164 const char *options[]);
167 close the connection to the database
169 int ldb_close(struct ldb_context *ldb);
173 search the database given a LDAP-like search expression
175 return the number of records found, or -1 on error
177 int ldb_search(struct ldb_context *ldb,
179 enum ldb_scope scope,
180 const char *expression,
181 const char * const *attrs, struct ldb_message ***res);
184 free a set of messages returned by ldb_search
186 int ldb_search_free(struct ldb_context *ldb, struct ldb_message **msgs);
190 add a record to the database. Will fail if a record with the given class and key
193 int ldb_add(struct ldb_context *ldb,
194 const struct ldb_message *message);
197 modify the specified attributes of a record
199 int ldb_modify(struct ldb_context *ldb,
200 const struct ldb_message *message);
203 rename a record in the database
205 int ldb_rename(struct ldb_context *ldb, const char *olddn, const char *newdn);
208 delete a record from the database
210 int ldb_delete(struct ldb_context *ldb, const char *dn);
214 return extended error information from the last call
216 const char *ldb_errstring(struct ldb_context *ldb);
219 casefold a string (should be UTF8, but at the moment it isn't)
221 char *ldb_casefold(struct ldb_context *ldb, const char *s);
224 ldif manipulation functions
226 int ldb_ldif_write(struct ldb_context *ldb,
227 int (*fprintf_fn)(void *, const char *, ...),
229 const struct ldb_ldif *ldif);
230 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *);
231 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
232 int (*fgetc_fn)(void *), void *private_data);
233 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
234 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char *s);
235 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
238 /* useful functions for ldb_message structure manipulation */
240 int ldb_dn_cmp(const char *dn1, const char *dn2);
241 int ldb_attr_cmp(const char *dn1, const char *dn2);
243 /* find an element within an message */
244 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg,
245 const char *attr_name);
247 /* compare two ldb_val values - return 0 on match */
248 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
250 /* find a value within an ldb_message_element */
251 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el,
252 struct ldb_val *val);
254 /* add a new empty element to a ldb_message */
255 int ldb_msg_add_empty(struct ldb_context *ldb,
256 struct ldb_message *msg, const char *attr_name, int flags);
258 /* add a element to a ldb_message */
259 int ldb_msg_add(struct ldb_context *ldb,
260 struct ldb_message *msg,
261 const struct ldb_message_element *el,
263 int ldb_msg_add_value(struct ldb_context *ldb,
264 struct ldb_message *msg,
265 const char *attr_name,
266 struct ldb_val *val);
267 int ldb_msg_add_string(struct ldb_context *ldb, struct ldb_message *msg,
268 const char *attr_name, char *str);
270 /* compare two message elements - return 0 on match */
271 int ldb_msg_element_compare(struct ldb_message_element *el1,
272 struct ldb_message_element *el2);
274 /* find elements in a message and convert to a specific type, with
275 a give default value if not found. Assumes that elements are
277 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
278 int ldb_msg_find_int(const struct ldb_message *msg,
279 const char *attr_name,
281 unsigned int ldb_msg_find_uint(const struct ldb_message *msg,
282 const char *attr_name,
283 unsigned int default_value);
284 int64_t ldb_msg_find_int64(const struct ldb_message *msg,
285 const char *attr_name,
286 int64_t default_value);
287 uint64_t ldb_msg_find_uint64(const struct ldb_message *msg,
288 const char *attr_name,
289 uint64_t default_value);
290 double ldb_msg_find_double(const struct ldb_message *msg,
291 const char *attr_name,
292 double default_value);
293 const char *ldb_msg_find_string(const struct ldb_message *msg,
294 const char *attr_name,
295 const char *default_value);
296 struct ldb_val ldb_val_dup(struct ldb_context *ldb,
297 const struct ldb_val *v);
300 this allows the user to choose their own allocation function
301 the allocation function should behave like a modern realloc()
302 function, which means that:
303 malloc(size) == alloc(context, NULL, size)
304 free(ptr) == alloc(context, ptr, 0)
305 realloc(ptr, size) == alloc(context, ptr, size)
306 The context argument is provided to allow for pool based allocators,
307 which often take a context argument
309 int ldb_set_alloc(struct ldb_context *ldb,
310 void *(*alloc)(const void *context, void *ptr, size_t size),
313 /* these are used as type safe versions of the ldb allocation functions */
314 #define ldb_malloc_p(ldb, type) (type *)ldb_malloc(ldb, sizeof(type))
315 #define ldb_malloc_array_p(ldb, type, count) (type *)ldb_realloc_array(ldb, NULL, sizeof(type), count)
316 #define ldb_realloc_p(ldb, p, type, count) (type *)ldb_realloc_array(ldb, p, sizeof(type), count)
318 void *ldb_realloc(struct ldb_context *ldb, void *ptr, size_t size);
319 void *ldb_malloc(struct ldb_context *ldb, size_t size);
320 void ldb_free(struct ldb_context *ldb, void *ptr);
321 void *ldb_strndup(struct ldb_context *ldb, const char *str, size_t maxlen);
322 void *ldb_strdup(struct ldb_context *ldb, const char *str);
323 void *ldb_realloc_array(struct ldb_context *ldb,
324 void *ptr, size_t el_size, unsigned count);
326 #ifndef PRINTF_ATTRIBUTE
327 #define PRINTF_ATTRIBUTE(a,b)
329 int ldb_asprintf(struct ldb_context *ldb, char **strp, const char *fmt, ...) PRINTF_ATTRIBUTE(3, 4);
332 this allows the user to set a debug function for error reporting
334 int ldb_set_debug(struct ldb_context *ldb,
335 void (*debug)(void *context, enum ldb_debug_level level,
336 const char *fmt, va_list ap),
339 /* this sets up debug to print messages on stderr */
340 int ldb_set_debug_stderr(struct ldb_context *ldb);