4 Copyright (C) Andrew Tridgell 2004
5 Copyright (C) Stefan Metzmacher 2004
6 Copyright (C) Simo Sorce 2005
8 ** NOTE! The following LGPL license applies to the ldb
9 ** library. This does NOT imply that all of Samba is released
12 This library is free software; you can redistribute it and/or
13 modify it under the terms of the GNU Lesser General Public
14 License as published by the Free Software Foundation; either
15 version 2 of the License, or (at your option) any later version.
17 This library is distributed in the hope that it will be useful,
18 but WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
22 You should have received a copy of the GNU Lesser General Public
23 License along with this library; if not, write to the Free Software
24 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
30 * Component: ldb header
32 * Description: defines for base ldb API
34 * Author: Andrew Tridgell
35 * Author: Stefan Metzmacher
42 major restrictions as compared to normal LDAP:
45 - each record must have a unique key field
46 - the key must be representable as a NULL terminated C string and may not
47 contain a comma or braces
49 major restrictions as compared to tdb:
51 - no explicit locking calls
52 UPDATE: we have transactions now, better than locking --SSS.
57 an individual lump of data in a result comes in this format. The
58 pointer will usually be to a UTF-8 string if the application is
59 sensible, but it can be to anything you like, including binary data
60 blobs of arbitrary size.
69 /* internal ldb exploded dn structures */
70 struct ldb_dn_component {
76 struct ldb_dn_component *components;
79 /* these flags are used in ldb_message_element.flags fields. The
80 LDA_FLAGS_MOD_* flags are used in ldap_modify() calls to specify
81 whether attributes are being added, deleted or modified */
82 #define LDB_FLAG_MOD_MASK 0x3
83 #define LDB_FLAG_MOD_ADD 1
84 #define LDB_FLAG_MOD_REPLACE 2
85 #define LDB_FLAG_MOD_DELETE 3
91 #define LDB_OID_COMPARATOR_AND "1.2.840.113556.1.4.803"
92 #define LDB_OID_COMPARATOR_OR "1.2.840.113556.1.4.804"
95 results are given back as arrays of ldb_message_element
97 struct ldb_message_element {
100 unsigned int num_values;
101 struct ldb_val *values;
106 a ldb_message represents all or part of a record. It can contain an arbitrary
111 unsigned int num_elements;
112 struct ldb_message_element *elements;
113 void *private_data; /* private to the backend */
116 enum ldb_changetype {
117 LDB_CHANGETYPE_NONE=0,
119 LDB_CHANGETYPE_DELETE,
120 LDB_CHANGETYPE_MODIFY
124 a ldif record - from ldif_read
127 enum ldb_changetype changetype;
128 struct ldb_message *msg;
131 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
133 LDB_SCOPE_ONELEVEL=1,
134 LDB_SCOPE_SUBTREE=2};
139 the fuction type for the callback used in traversing the database
141 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
144 /* debugging uses one of the following levels */
145 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR,
146 LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
149 the user can optionally supply a debug function. The function
150 is based on the vfprintf() style of interface, but with the addition
153 struct ldb_debug_ops {
154 void (*debug)(void *context, enum ldb_debug_level level,
155 const char *fmt, va_list ap);
159 #define LDB_FLG_RDONLY 1
160 #define LDB_FLG_NOSYNC 2
162 #ifndef PRINTF_ATTRIBUTE
163 #define PRINTF_ATTRIBUTE(a,b)
166 /* structures for ldb_parse_tree handling code */
167 enum ldb_parse_op { LDB_OP_AND=1, LDB_OP_OR=2, LDB_OP_NOT=3,
168 LDB_OP_EQUALITY=4, LDB_OP_SUBSTRING=5,
169 LDB_OP_GREATER=6, LDB_OP_LESS=7, LDB_OP_PRESENT=8,
170 LDB_OP_APPROX=9, LDB_OP_EXTENDED=10 };
172 struct ldb_parse_tree {
173 enum ldb_parse_op operation;
176 struct ldb_parse_tree *child;
180 struct ldb_val value;
184 int start_with_wildcard;
185 int end_with_wildcard;
186 struct ldb_val **chunks;
193 struct ldb_val value;
199 struct ldb_val value;
202 unsigned int num_elements;
203 struct ldb_parse_tree **elements;
208 struct ldb_parse_tree *ldb_parse_tree(void *mem_ctx, const char *s);
209 char *ldb_filter_from_tree(void *mem_ctx, struct ldb_parse_tree *tree);
210 char *ldb_binary_encode(void *ctx, struct ldb_val val);
211 char *ldb_binary_encode_string(void *mem_ctx, const char *string);
214 functions for controlling attribute handling
216 typedef int (*ldb_attr_handler_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, struct ldb_val *);
217 typedef int (*ldb_attr_comparison_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, const struct ldb_val *);
219 struct ldb_attrib_handler {
222 /* LDB_ATTR_FLAG_* */
225 /* convert from ldif to binary format */
226 ldb_attr_handler_t ldif_read_fn;
228 /* convert from binary to ldif format */
229 ldb_attr_handler_t ldif_write_fn;
231 /* canonicalise a value, for use by indexing and dn construction */
232 ldb_attr_handler_t canonicalise_fn;
234 /* compare two values */
235 ldb_attr_comparison_t comparison_fn;
238 #define LDB_ATTR_FLAG_HIDDEN (1<<0) /* the attribute is not returned by default */
239 #define LDB_ATTR_FLAG_CONSTRUCTED (1<<1) /* the attribute is constructed from other attributes */
242 /* well-known ldap attribute syntaxes - see rfc2252 section 4.3.2 */
243 #define LDB_SYNTAX_DN "1.3.6.1.4.1.1466.115.121.1.12"
244 #define LDB_SYNTAX_DIRECTORY_STRING "1.3.6.1.4.1.1466.115.121.1.15"
245 #define LDB_SYNTAX_INTEGER "1.3.6.1.4.1.1466.115.121.1.27"
246 #define LDB_SYNTAX_OCTET_STRING "1.3.6.1.4.1.1466.115.121.1.40"
247 #define LDB_SYNTAX_UTC_TIME "1.3.6.1.4.1.1466.115.121.1.53"
248 #define LDB_SYNTAX_OBJECTCLASS "LDB_SYNTAX_OBJECTCLASS"
250 /* sorting helpers */
251 typedef int (*ldb_qsort_cmp_fn_t) (const void *, const void *, const void *);
253 #define LDB_CONTROL_PAGED_RESULTS_OID "1.2.840.113556.1.4.319"
254 #define LDB_CONTROL_EXTENDED_DN_OID "1.2.840.113556.1.4.529"
255 #define LDB_CONTROL_SERVER_SORT_OID "1.2.840.113556.1.4.473"
256 #define LDB_CONTROL_SORT_RESP_OID "1.2.840.113556.1.4.474"
258 struct ldb_paged_control {
264 struct ldb_extended_dn_control {
268 struct ldb_server_sort_control {
274 struct ldb_sort_resp_control {
285 struct ldb_credentials;
287 enum ldb_request_type {
298 struct ldb_message **msgs;
299 struct ldb_control **controls;
303 const struct ldb_dn *base;
304 enum ldb_scope scope;
305 struct ldb_parse_tree *tree;
306 const char * const *attrs;
307 struct ldb_result *res;
311 const struct ldb_message *message;
315 const struct ldb_message *message;
319 const struct ldb_dn *dn;
323 const struct ldb_dn *olddn;
324 const struct ldb_dn *newdn;
327 struct ldb_register_control {
336 struct ldb_search search;
338 struct ldb_modify mod;
339 struct ldb_delete del;
340 struct ldb_rename rename;
341 struct ldb_register_control reg;
344 struct ldb_control **controls;
345 struct ldb_credentials *creds;
348 int ldb_request(struct ldb_context *ldb, struct ldb_request *request);
351 initialise a ldb context
353 struct ldb_context *ldb_init(void *mem_ctx);
356 connect to a database. The URL can either be one of the following forms
360 flags is made up of LDB_FLG_*
362 the options are passed uninterpreted to the backend, and are
365 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
368 search the database given a LDAP-like search expression
370 return the number of records found, or -1 on error
372 use talloc_free to free the ldb_message returned
374 int ldb_search(struct ldb_context *ldb,
375 const struct ldb_dn *base,
376 enum ldb_scope scope,
377 const char *expression,
378 const char * const *attrs, struct ldb_result **res);
381 like ldb_search() but takes a parse tree
383 int ldb_search_bytree(struct ldb_context *ldb,
384 const struct ldb_dn *base,
385 enum ldb_scope scope,
386 struct ldb_parse_tree *tree,
387 const char * const *attrs, struct ldb_result **res);
390 add a record to the database. Will fail if a record with the given class and key
393 int ldb_add(struct ldb_context *ldb,
394 const struct ldb_message *message);
397 modify the specified attributes of a record
399 int ldb_modify(struct ldb_context *ldb,
400 const struct ldb_message *message);
403 rename a record in the database
405 int ldb_rename(struct ldb_context *ldb, const struct ldb_dn *olddn, const struct ldb_dn *newdn);
408 delete a record from the database
410 int ldb_delete(struct ldb_context *ldb, const struct ldb_dn *dn);
415 int ldb_transaction_start(struct ldb_context *ldb);
420 int ldb_transaction_commit(struct ldb_context *ldb);
425 int ldb_transaction_cancel(struct ldb_context *ldb);
429 return extended error information from the last call
431 const char *ldb_errstring(struct ldb_context *ldb);
434 casefold a string (should be UTF8, but at the moment it isn't)
436 char *ldb_casefold(void *mem_ctx, const char *s);
437 int ldb_caseless_cmp(const char *s1, const char *s2);
440 ldif manipulation functions
442 int ldb_ldif_write(struct ldb_context *ldb,
443 int (*fprintf_fn)(void *, const char *, ...),
445 const struct ldb_ldif *ldif);
446 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *);
447 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
448 int (*fgetc_fn)(void *), void *private_data);
449 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
450 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
451 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
452 char *ldb_base64_encode(void *mem_ctx, const char *buf, int len);
453 int ldb_base64_decode(char *s);
454 int ldb_attrib_add_handlers(struct ldb_context *ldb,
455 const struct ldb_attrib_handler *handlers,
456 unsigned num_handlers);
458 /* The following definitions come from lib/ldb/common/ldb_dn.c */
460 int ldb_dn_is_special(const struct ldb_dn *dn);
461 int ldb_dn_check_special(const struct ldb_dn *dn, const char *check);
462 char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
463 struct ldb_dn *ldb_dn_new(void *mem_ctx);
464 struct ldb_dn *ldb_dn_explode(void *mem_ctx, const char *dn);
465 struct ldb_dn *ldb_dn_explode_or_special(void *mem_ctx, const char *dn);
466 char *ldb_dn_linearize(void *mem_ctx, const struct ldb_dn *edn);
467 char *ldb_dn_linearize_casefold(struct ldb_context *ldb, const struct ldb_dn *edn);
468 int ldb_dn_compare_base(struct ldb_context *ldb, const struct ldb_dn *base, const struct ldb_dn *dn);
469 int ldb_dn_compare(struct ldb_context *ldb, const struct ldb_dn *edn0, const struct ldb_dn *edn1);
470 struct ldb_dn *ldb_dn_casefold(struct ldb_context *ldb, const struct ldb_dn *edn);
471 struct ldb_dn *ldb_dn_explode_casefold(struct ldb_context *ldb, const char *dn);
472 struct ldb_dn *ldb_dn_copy_partial(void *mem_ctx, const struct ldb_dn *dn, int num_el);
473 struct ldb_dn *ldb_dn_copy(void *mem_ctx, const struct ldb_dn *dn);
474 struct ldb_dn *ldb_dn_get_parent(void *mem_ctx, const struct ldb_dn *dn);
475 struct ldb_dn_component *ldb_dn_build_component(void *mem_ctx, const char *attr,
477 struct ldb_dn *ldb_dn_build_child(void *mem_ctx, const char *attr,
479 const struct ldb_dn *base);
480 struct ldb_dn *ldb_dn_make_child(void *mem_ctx,
481 const struct ldb_dn_component *component,
482 const struct ldb_dn *base);
483 struct ldb_dn *ldb_dn_compose(void *mem_ctx, const struct ldb_dn *dn1, const struct ldb_dn *dn2);
484 struct ldb_dn *ldb_dn_string_compose(void *mem_ctx, const struct ldb_dn *base, const char *child_fmt, ...) PRINTF_ATTRIBUTE(3,4);
485 struct ldb_dn_component *ldb_dn_get_rdn(void *mem_ctx, const struct ldb_dn *dn);
487 /* useful functions for ldb_message structure manipulation */
488 int ldb_dn_cmp(struct ldb_context *ldb, const char *dn1, const char *dn2);
489 int ldb_attr_cmp(const char *attr1, const char *attr2);
490 int ldb_attr_dn(const char *attr);
491 char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
493 /* create an empty message */
494 struct ldb_message *ldb_msg_new(void *mem_ctx);
496 /* find an element within an message */
497 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg,
498 const char *attr_name);
500 /* compare two ldb_val values - return 0 on match */
501 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
503 /* find a value within an ldb_message_element */
504 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el,
505 struct ldb_val *val);
507 /* add a new empty element to a ldb_message */
508 int ldb_msg_add_empty(struct ldb_message *msg, const char *attr_name, int flags);
510 /* add a element to a ldb_message */
511 int ldb_msg_add(struct ldb_message *msg,
512 const struct ldb_message_element *el,
514 int ldb_msg_add_value(struct ldb_message *msg,
515 const char *attr_name,
516 const struct ldb_val *val);
517 int ldb_msg_add_string(struct ldb_message *msg,
518 const char *attr_name, const char *str);
519 int ldb_msg_add_fmt(struct ldb_message *msg,
520 const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
522 /* compare two message elements - return 0 on match */
523 int ldb_msg_element_compare(struct ldb_message_element *el1,
524 struct ldb_message_element *el2);
526 /* find elements in a message and convert to a specific type, with
527 a give default value if not found. Assumes that elements are
529 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
530 int ldb_msg_find_int(const struct ldb_message *msg,
531 const char *attr_name,
533 unsigned int ldb_msg_find_uint(const struct ldb_message *msg,
534 const char *attr_name,
535 unsigned int default_value);
536 int64_t ldb_msg_find_int64(const struct ldb_message *msg,
537 const char *attr_name,
538 int64_t default_value);
539 uint64_t ldb_msg_find_uint64(const struct ldb_message *msg,
540 const char *attr_name,
541 uint64_t default_value);
542 double ldb_msg_find_double(const struct ldb_message *msg,
543 const char *attr_name,
544 double default_value);
545 const char *ldb_msg_find_string(const struct ldb_message *msg,
546 const char *attr_name,
547 const char *default_value);
549 void ldb_msg_sort_elements(struct ldb_message *msg);
551 struct ldb_message *ldb_msg_copy_shallow(void *mem_ctx,
552 const struct ldb_message *msg);
553 struct ldb_message *ldb_msg_copy(void *mem_ctx,
554 const struct ldb_message *msg);
556 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb,
557 const struct ldb_message *msg);
560 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb,
561 struct ldb_message *msg1,
562 struct ldb_message *msg2);
564 int ldb_msg_sanity_check(const struct ldb_message *msg);
566 struct ldb_val ldb_val_dup(void *mem_ctx, const struct ldb_val *v);
569 this allows the user to set a debug function for error reporting
571 int ldb_set_debug(struct ldb_context *ldb,
572 void (*debug)(void *context, enum ldb_debug_level level,
573 const char *fmt, va_list ap),
576 /* this sets up debug to print messages on stderr */
577 int ldb_set_debug_stderr(struct ldb_context *ldb);
579 /* control backend specific opaque values */
580 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
581 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
583 const struct ldb_attrib_handler *ldb_attrib_handler(struct ldb_context *ldb,
587 const char **ldb_attr_list_copy(void *mem_ctx, const char * const *attrs);
588 int ldb_attr_in_list(const char * const *attrs, const char *attr);
591 void ldb_parse_tree_attr_replace(struct ldb_parse_tree *tree,
593 const char *replace);
595 int ldb_msg_rename_attr(struct ldb_message *msg, const char *attr, const char *replace);
596 int ldb_msg_copy_attr(struct ldb_message *msg, const char *attr, const char *replace);
597 void ldb_msg_remove_attr(struct ldb_message *msg, const char *attr);
599 char *ldb_timestring(void *mem_ctx, time_t t);
600 time_t ldb_string_to_time(const char *s);
602 char *ldb_dn_canonical_string(void *mem_ctx, const struct ldb_dn *dn);
603 char *ldb_dn_canonical_ex_string(void *mem_ctx, const struct ldb_dn *dn);
606 void ldb_qsort (void *const pbase, size_t total_elems, size_t size, void *opaque, ldb_qsort_cmp_fn_t cmp);