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.
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
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"
83 results are given back as arrays of ldb_message_element
85 struct ldb_message_element {
88 unsigned int num_values;
89 struct ldb_val *values;
94 a ldb_message represents all or part of a record. It can contain an arbitrary
99 unsigned int num_elements;
100 struct ldb_message_element *elements;
101 void *private_data; /* private to the backend */
104 enum ldb_changetype {
105 LDB_CHANGETYPE_NONE=0,
107 LDB_CHANGETYPE_DELETE,
108 LDB_CHANGETYPE_MODIFY
112 a ldif record - from ldif_read
115 enum ldb_changetype changetype;
116 struct ldb_message *msg;
119 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
121 LDB_SCOPE_ONELEVEL=1,
122 LDB_SCOPE_SUBTREE=2};
127 the fuction type for the callback used in traversing the database
129 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
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};
139 the user can optionally supply a debug function. The function
140 is based on the vfprintf() style of interface, but with the addition
143 struct ldb_debug_ops {
144 void (*debug)(void *context, enum ldb_debug_level level,
145 const char *fmt, va_list ap);
149 #define LDB_FLG_RDONLY 1
151 #ifndef PRINTF_ATTRIBUTE
152 #define PRINTF_ATTRIBUTE(a,b)
156 /* structues for ldb_parse_tree handling code */
157 enum ldb_parse_op {LDB_OP_SIMPLE=1, LDB_OP_EXTENDED=2,
158 LDB_OP_SUBSTRING=3, LDB_OP_PRESENT=4,
159 LDB_OP_AND='&', LDB_OP_OR='|', LDB_OP_NOT='!'};
161 struct ldb_parse_tree {
162 enum ldb_parse_op operation;
166 struct ldb_val value;
173 int start_with_wildcard;
174 int end_with_wildcard;
175 struct ldb_val **chunks;
181 struct ldb_val value;
184 unsigned int num_elements;
185 struct ldb_parse_tree **elements;
188 struct ldb_parse_tree *child;
193 struct ldb_parse_tree *ldb_parse_tree(void *mem_ctx, const char *s);
194 char *ldb_filter_from_tree(void *mem_ctx, struct ldb_parse_tree *tree);
195 char *ldb_binary_encode(void *ctx, struct ldb_val val);
199 functions for controlling attribute handling
201 typedef int (*ldb_attr_handler_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, struct ldb_val *);
202 typedef int (*ldb_attr_comparison_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, const struct ldb_val *);
204 struct ldb_attrib_handler {
207 /* LDB_ATTR_FLAG_* */
210 /* convert from ldif to binary format */
211 ldb_attr_handler_t ldif_read_fn;
213 /* convert from binary to ldif format */
214 ldb_attr_handler_t ldif_write_fn;
216 /* canonicalise a value, for use by indexing and dn construction */
217 ldb_attr_handler_t canonicalise_fn;
219 /* compare two values */
220 ldb_attr_comparison_t comparison_fn;
223 #define LDB_ATTR_FLAG_HIDDEN (1<<0)
225 /* well-known ldap attribute syntaxes - see rfc2252 section 4.3.2 */
226 #define LDB_SYNTAX_DN "1.3.6.1.4.1.1466.115.121.1.12"
227 #define LDB_SYNTAX_DIRECTORY_STRING "1.3.6.1.4.1.1466.115.121.1.15"
228 #define LDB_SYNTAX_INTEGER "1.3.6.1.4.1.1466.115.121.1.27"
229 #define LDB_SYNTAX_OCTET_STRING "1.3.6.1.4.1.1466.115.121.1.40"
230 #define LDB_SYNTAX_OBJECTCLASS "LDB_SYNTAX_OBJECTCLASS"
233 initialise a ldb context
235 struct ldb_context *ldb_init(void *mem_ctx);
238 connect to a database. The URL can either be one of the following forms
242 flags is made up of LDB_FLG_*
244 the options are passed uninterpreted to the backend, and are
247 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
250 search the database given a LDAP-like search expression
252 return the number of records found, or -1 on error
254 use talloc_free to free the ldb_message returned
256 int ldb_search(struct ldb_context *ldb,
258 enum ldb_scope scope,
259 const char *expression,
260 const char * const *attrs, struct ldb_message ***res);
263 like ldb_search() but takes a parse tree
265 int ldb_search_bytree(struct ldb_context *ldb,
267 enum ldb_scope scope,
268 struct ldb_parse_tree *tree,
269 const char * const *attrs, struct ldb_message ***res);
272 add a record to the database. Will fail if a record with the given class and key
275 int ldb_add(struct ldb_context *ldb,
276 const struct ldb_message *message);
279 modify the specified attributes of a record
281 int ldb_modify(struct ldb_context *ldb,
282 const struct ldb_message *message);
285 rename a record in the database
287 int ldb_rename(struct ldb_context *ldb, const char *olddn, const char *newdn);
292 int ldb_lock(struct ldb_context *ldb, const char *lockname);
297 int ldb_unlock(struct ldb_context *ldb, const char *lockname);
300 delete a record from the database
302 int ldb_delete(struct ldb_context *ldb, const char *dn);
306 return extended error information from the last call
308 const char *ldb_errstring(struct ldb_context *ldb);
311 casefold a string (should be UTF8, but at the moment it isn't)
313 char *ldb_casefold(void *mem_ctx, const char *s);
314 int ldb_caseless_cmp(const char *s1, const char *s2);
317 ldif manipulation functions
319 int ldb_ldif_write(struct ldb_context *ldb,
320 int (*fprintf_fn)(void *, const char *, ...),
322 const struct ldb_ldif *ldif);
323 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *);
324 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
325 int (*fgetc_fn)(void *), void *private_data);
326 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
327 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
328 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
329 char *ldb_base64_encode(void *mem_ctx, const char *buf, int len);
330 int ldb_base64_decode(char *s);
331 int ldb_attrib_add_handlers(struct ldb_context *ldb,
332 const struct ldb_attrib_handler *handlers,
333 unsigned num_handlers);
336 /* useful functions for ldb_message structure manipulation */
338 int ldb_dn_cmp(struct ldb_context *ldb, const char *dn1, const char *dn2);
339 int ldb_attr_cmp(const char *dn1, const char *dn2);
342 char *ldb_dn_fold(void * mem_ctx,
345 int (* case_fold_attr_fn)(void * user_data, char * attr));
347 /* create an empty message */
348 struct ldb_message *ldb_msg_new(void *mem_ctx);
350 /* find an element within an message */
351 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg,
352 const char *attr_name);
354 /* compare two ldb_val values - return 0 on match */
355 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
357 /* find a value within an ldb_message_element */
358 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el,
359 struct ldb_val *val);
361 /* add a new empty element to a ldb_message */
362 int ldb_msg_add_empty(struct ldb_context *ldb,
363 struct ldb_message *msg, const char *attr_name, int flags);
365 /* add a element to a ldb_message */
366 int ldb_msg_add(struct ldb_context *ldb,
367 struct ldb_message *msg,
368 const struct ldb_message_element *el,
370 int ldb_msg_add_value(struct ldb_context *ldb,
371 struct ldb_message *msg,
372 const char *attr_name,
373 const struct ldb_val *val);
374 int ldb_msg_add_string(struct ldb_context *ldb, struct ldb_message *msg,
375 const char *attr_name, const char *str);
376 int ldb_msg_add_fmt(struct ldb_context *ldb, struct ldb_message *msg,
377 const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(4,5);
379 /* compare two message elements - return 0 on match */
380 int ldb_msg_element_compare(struct ldb_message_element *el1,
381 struct ldb_message_element *el2);
383 /* find elements in a message and convert to a specific type, with
384 a give default value if not found. Assumes that elements are
386 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
387 int ldb_msg_find_int(const struct ldb_message *msg,
388 const char *attr_name,
390 unsigned int ldb_msg_find_uint(const struct ldb_message *msg,
391 const char *attr_name,
392 unsigned int default_value);
393 int64_t ldb_msg_find_int64(const struct ldb_message *msg,
394 const char *attr_name,
395 int64_t default_value);
396 uint64_t ldb_msg_find_uint64(const struct ldb_message *msg,
397 const char *attr_name,
398 uint64_t default_value);
399 double ldb_msg_find_double(const struct ldb_message *msg,
400 const char *attr_name,
401 double default_value);
402 const char *ldb_msg_find_string(const struct ldb_message *msg,
403 const char *attr_name,
404 const char *default_value);
406 void ldb_msg_sort_elements(struct ldb_message *msg);
408 void ldb_msg_free(struct ldb_context *ldb, struct ldb_message *msg);
410 struct ldb_message *ldb_msg_copy(struct ldb_context *ldb,
411 const struct ldb_message *msg);
413 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb,
414 const struct ldb_message *msg);
417 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb,
418 struct ldb_message *msg1,
419 struct ldb_message *msg2);
421 struct ldb_val ldb_val_dup(void *mem_ctx, const struct ldb_val *v);
424 this allows the user to set a debug function for error reporting
426 int ldb_set_debug(struct ldb_context *ldb,
427 void (*debug)(void *context, enum ldb_debug_level level,
428 const char *fmt, va_list ap),
431 /* this sets up debug to print messages on stderr */
432 int ldb_set_debug_stderr(struct ldb_context *ldb);
434 /* control backend specific opaque values */
435 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
436 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);