source/lib/ldb/include/ldb.h

   1 /*
   2    ldb database library
   3
   4    Copyright (C) Andrew Tridgell  2004
   5    Copyright (C) Stefan Metzmacher  2004
   6    Copyright (C) Simo Sorce  2005
   7
   8      ** NOTE! The following LGPL license applies to the ldb
   9      ** library. This does NOT imply that all of Samba is released
  10      ** under the LGPL
  11
  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.
  16
  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.
  21
  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
  25 */
  26
  27 /*
  28  *  Name: ldb
  29  *
  30  *  Component: ldb header
  31  *
  32  *  Description: defines for base ldb API
  33  *
  34  *  Author: Andrew Tridgell
  35  *  Author: Stefan Metzmacher
  36  */
  37
  38 #ifndef _LDB_H_
  39 #define _LDB_H_ 1
  40
  41 /*
  42   major restrictions as compared to normal LDAP:
  43
  44      - no async calls.
  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
  48
  49   major restrictions as compared to tdb:
  50
  51      - no explicit locking calls
  52      UPDATE: we have transactions now, better than locking --SSS.
  53
  54 */
  55
  56 /*
  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.
  61 */
  62 #ifndef ldb_val
  63 struct ldb_val {
  64         uint8_t *data;
  65         size_t length;
  66 };
  67 #endif
  68
  69 /* internal ldb exploded dn structures */
  70 struct ldb_dn_component {
  71         char *name;
  72         struct ldb_val value;
  73 };
  74 struct ldb_dn {
  75         int comp_num;
  76         struct ldb_dn_component *components;
  77 };
  78
  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
  86
  87
  88 /*
  89   well known object IDs
  90 */
  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"
  93
  94 /*
  95   results are given back as arrays of ldb_message_element
  96 */
  97 struct ldb_message_element {
  98         unsigned int flags;
  99         const char *name;
 100         unsigned int num_values;
 101         struct ldb_val *values;
 102 };
 103
 104
 105 /*
 106   a ldb_message represents all or part of a record. It can contain an arbitrary
 107   number of elements.
 108 */
 109 struct ldb_message {
 110         struct ldb_dn *dn;
 111         unsigned int num_elements;
 112         struct ldb_message_element *elements;
 113         void *private_data; /* private to the backend */
 114 };
 115
 116 enum ldb_changetype {
 117         LDB_CHANGETYPE_NONE=0,
 118         LDB_CHANGETYPE_ADD,
 119         LDB_CHANGETYPE_DELETE,
 120         LDB_CHANGETYPE_MODIFY
 121 };
 122
 123 /*
 124   a ldif record - from ldif_read
 125 */
 126 struct ldb_ldif {
 127         enum ldb_changetype changetype;
 128         struct ldb_message *msg;
 129 };
 130
 131 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
 132                 LDB_SCOPE_BASE=0,
 133                 LDB_SCOPE_ONELEVEL=1,
 134                 LDB_SCOPE_SUBTREE=2};
 135
 136 struct ldb_context;
 137
 138 /*
 139   the fuction type for the callback used in traversing the database
 140 */
 141 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
 142
 143
 144 struct ldb_module;
 145
 146 /* module initialisation function */
 147 typedef struct ldb_module *(*ldb_module_init_t)(struct ldb_context *, const char **);
 148
 149
 150 /* debugging uses one of the following levels */
 151 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR,
 152                       LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
 153
 154 /*
 155   the user can optionally supply a debug function. The function
 156   is based on the vfprintf() style of interface, but with the addition
 157   of a severity level
 158 */
 159 struct ldb_debug_ops {
 160         void (*debug)(void *context, enum ldb_debug_level level,
 161                       const char *fmt, va_list ap);
 162         void *context;
 163 };
 164
 165 #define LDB_FLG_RDONLY 1
 166 #define LDB_FLG_NOSYNC 2
 167
 168 #ifndef PRINTF_ATTRIBUTE
 169 #define PRINTF_ATTRIBUTE(a,b)
 170 #endif
 171
 172 /* structures for ldb_parse_tree handling code */
 173 enum ldb_parse_op { LDB_OP_AND=1, LDB_OP_OR=2, LDB_OP_NOT=3,
 174                     LDB_OP_EQUALITY=4, LDB_OP_SUBSTRING=5,
 175                     LDB_OP_GREATER=6, LDB_OP_LESS=7, LDB_OP_PRESENT=8,
 176                     LDB_OP_APPROX=9, LDB_OP_EXTENDED=10 };
 177
 178 struct ldb_parse_tree {
 179         enum ldb_parse_op operation;
 180         union {
 181                 struct {
 182                         struct ldb_parse_tree *child;
 183                 } isnot;
 184                 struct {
 185                         const char *attr;
 186                         struct ldb_val value;
 187                 } equality;
 188                 struct {
 189                         const char *attr;
 190                         int start_with_wildcard;
 191                         int end_with_wildcard;
 192                         struct ldb_val **chunks;
 193                 } substring;
 194                 struct {
 195                         const char *attr;
 196                 } present;
 197                 struct {
 198                         const char *attr;
 199                         struct ldb_val value;
 200                 } comparison;
 201                 struct {
 202                         const char *attr;
 203                         int dnAttributes;
 204                         char *rule_id;
 205                         struct ldb_val value;
 206                 } extended;
 207                 struct {
 208                         unsigned int num_elements;
 209                         struct ldb_parse_tree **elements;
 210                 } list;
 211         } u;
 212 };
 213
 214 struct ldb_parse_tree *ldb_parse_tree(void *mem_ctx, const char *s);
 215 char *ldb_filter_from_tree(void *mem_ctx, struct ldb_parse_tree *tree);
 216 char *ldb_binary_encode(void *ctx, struct ldb_val val);
 217
 218
 219 /*
 220   functions for controlling attribute handling
 221 */
 222 typedef int (*ldb_attr_handler_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, struct ldb_val *);
 223 typedef int (*ldb_attr_comparison_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, const struct ldb_val *);
 224
 225 struct ldb_attrib_handler {
 226         const char *attr;
 227
 228         /* LDB_ATTR_FLAG_* */
 229         unsigned flags;
 230
 231         /* convert from ldif to binary format */
 232         ldb_attr_handler_t ldif_read_fn;
 233
 234         /* convert from binary to ldif format */
 235         ldb_attr_handler_t ldif_write_fn;
 236
 237         /* canonicalise a value, for use by indexing and dn construction */
 238         ldb_attr_handler_t canonicalise_fn;
 239
 240         /* compare two values */
 241         ldb_attr_comparison_t comparison_fn;
 242 };
 243
 244 #define LDB_ATTR_FLAG_HIDDEN       (1<<0) /* the attribute is not returned by default */
 245 #define LDB_ATTR_FLAG_CONSTRUCTED  (1<<1) /* the attribute is constructed from other attributes */
 246
 247
 248 /* well-known ldap attribute syntaxes - see rfc2252 section 4.3.2 */
 249 #define LDB_SYNTAX_DN                   "1.3.6.1.4.1.1466.115.121.1.12"
 250 #define LDB_SYNTAX_DIRECTORY_STRING     "1.3.6.1.4.1.1466.115.121.1.15"
 251 #define LDB_SYNTAX_INTEGER              "1.3.6.1.4.1.1466.115.121.1.27"
 252 #define LDB_SYNTAX_OCTET_STRING         "1.3.6.1.4.1.1466.115.121.1.40"
 253 #define LDB_SYNTAX_UTC_TIME             "1.3.6.1.4.1.1466.115.121.1.53"
 254 #define LDB_SYNTAX_OBJECTCLASS          "LDB_SYNTAX_OBJECTCLASS"
 255
 256 struct ldb_controls;
 257 struct ldb_credentials;
 258
 259 enum ldb_request_type {
 260         LDB_REQ_SEARCH,
 261         LDB_REQ_ADD,
 262         LDB_REQ_MODIFY,
 263         LDB_REQ_DELETE,
 264         LDB_REQ_RENAME
 265 };
 266
 267 struct ldb_result {
 268         unsigned int count;
 269         struct ldb_message **msgs;
 270 };
 271
 272 struct ldb_search {
 273         const struct ldb_dn *base;
 274         enum ldb_scope scope;
 275         struct ldb_parse_tree *tree;
 276         const char * const *attrs;
 277         struct ldb_result *res;
 278 };
 279
 280 struct ldb_add {
 281         const struct ldb_message *message;
 282 };
 283
 284 struct  ldb_modify {
 285         const struct ldb_message *message;
 286 };
 287
 288 struct ldb_delete {
 289         const struct ldb_dn *dn;
 290 };
 291
 292 struct ldb_rename {
 293         const struct ldb_dn *olddn;
 294         const struct ldb_dn *newdn;
 295 };
 296
 297 struct ldb_request {
 298
 299         int operation;
 300
 301         union {
 302                 struct ldb_search search;
 303                 struct ldb_add    add;
 304                 struct ldb_modify mod;
 305                 struct ldb_delete del;
 306                 struct ldb_rename rename;
 307         } op;
 308
 309         struct ldb_controls *controls;
 310         struct ldb_credentials *creds;
 311 };
 312
 313 int ldb_request(struct ldb_context *ldb, struct ldb_request *request);
 314
 315 /*
 316   initialise a ldb context
 317 */
 318 struct ldb_context *ldb_init(void *mem_ctx);
 319
 320 /*
 321  connect to a database. The URL can either be one of the following forms
 322    ldb://path
 323    ldapi://path
 324
 325    flags is made up of LDB_FLG_*
 326
 327    the options are passed uninterpreted to the backend, and are
 328    backend specific
 329 */
 330 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
 331
 332 /*
 333   search the database given a LDAP-like search expression
 334
 335   return the number of records found, or -1 on error
 336
 337   use talloc_free to free the ldb_message returned
 338 */
 339 int ldb_search(struct ldb_context *ldb,
 340                const struct ldb_dn *base,
 341                enum ldb_scope scope,
 342                const char *expression,
 343                const char * const *attrs, struct ldb_result **res);
 344
 345 /*
 346   like ldb_search() but takes a parse tree
 347 */
 348 int ldb_search_bytree(struct ldb_context *ldb,
 349                       const struct ldb_dn *base,
 350                       enum ldb_scope scope,
 351                       struct ldb_parse_tree *tree,
 352                       const char * const *attrs, struct ldb_result **res);
 353
 354 /*
 355   add a record to the database. Will fail if a record with the given class and key
 356   already exists
 357 */
 358 int ldb_add(struct ldb_context *ldb,
 359             const struct ldb_message *message);
 360
 361 /*
 362   modify the specified attributes of a record
 363 */
 364 int ldb_modify(struct ldb_context *ldb,
 365                const struct ldb_message *message);
 366
 367 /*
 368   rename a record in the database
 369 */
 370 int ldb_rename(struct ldb_context *ldb, const struct ldb_dn *olddn, const struct ldb_dn *newdn);
 371
 372 /*
 373   delete a record from the database
 374 */
 375 int ldb_delete(struct ldb_context *ldb, const struct ldb_dn *dn);
 376
 377 /*
 378   start a transaction
 379 */
 380 int ldb_transaction_start(struct ldb_context *ldb);
 381
 382 /*
 383   commit a transaction
 384 */
 385 int ldb_transaction_commit(struct ldb_context *ldb);
 386
 387 /*
 388   cancel a transaction
 389 */
 390 int ldb_transaction_cancel(struct ldb_context *ldb);
 391
 392
 393 /*
 394   return extended error information from the last call
 395 */
 396 const char *ldb_errstring(struct ldb_context *ldb);
 397
 398 /*
 399   casefold a string (should be UTF8, but at the moment it isn't)
 400 */
 401 char *ldb_casefold(void *mem_ctx, const char *s);
 402 int ldb_caseless_cmp(const char *s1, const char *s2);
 403
 404 /*
 405   ldif manipulation functions
 406 */
 407 int ldb_ldif_write(struct ldb_context *ldb,
 408                    int (*fprintf_fn)(void *, const char *, ...),
 409                    void *private_data,
 410                    const struct ldb_ldif *ldif);
 411 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *);
 412 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
 413                                int (*fgetc_fn)(void *), void *private_data);
 414 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
 415 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
 416 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
 417 char *ldb_base64_encode(void *mem_ctx, const char *buf, int len);
 418 int ldb_base64_decode(char *s);
 419 int ldb_attrib_add_handlers(struct ldb_context *ldb,
 420                             const struct ldb_attrib_handler *handlers,
 421                             unsigned num_handlers);
 422
 423 /* The following definitions come from lib/ldb/common/ldb_dn.c  */
 424
 425 int ldb_dn_is_special(const struct ldb_dn *dn);
 426 int ldb_dn_check_special(const struct ldb_dn *dn, const char *check);
 427 char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
 428 struct ldb_dn *ldb_dn_new(void *mem_ctx);
 429 struct ldb_dn *ldb_dn_explode(void *mem_ctx, const char *dn);
 430 char *ldb_dn_linearize(void *mem_ctx, const struct ldb_dn *edn);
 431 char *ldb_dn_linearize_casefold(struct ldb_context *ldb, const struct ldb_dn *edn);
 432 int ldb_dn_compare_base(struct ldb_context *ldb, const struct ldb_dn *base, const struct ldb_dn *dn);
 433 int ldb_dn_compare(struct ldb_context *ldb, const struct ldb_dn *edn0, const struct ldb_dn *edn1);
 434 struct ldb_dn *ldb_dn_casefold(struct ldb_context *ldb, const struct ldb_dn *edn);
 435 struct ldb_dn *ldb_dn_explode_casefold(struct ldb_context *ldb, const char *dn);
 436 struct ldb_dn *ldb_dn_copy_partial(void *mem_ctx, const struct ldb_dn *dn, int num_el);
 437 struct ldb_dn *ldb_dn_copy(void *mem_ctx, const struct ldb_dn *dn);
 438 struct ldb_dn *ldb_dn_get_parent(void *mem_ctx, const struct ldb_dn *dn);
 439 struct ldb_dn_component *ldb_dn_build_component(void *mem_ctx, const char *attr,
 440                                                                const char *val);
 441 struct ldb_dn *ldb_dn_build_child(void *mem_ctx, const char *attr,
 442                                                  const char * value,
 443                                                  const struct ldb_dn *base);
 444 struct ldb_dn *ldb_dn_make_child(void *mem_ctx,
 445                                  const struct ldb_dn_component *component,
 446                                  const struct ldb_dn *base);
 447 struct ldb_dn *ldb_dn_compose(void *mem_ctx, const struct ldb_dn *dn1, const struct ldb_dn *dn2);
 448 struct ldb_dn *ldb_dn_string_compose(void *mem_ctx, const struct ldb_dn *base, const char *child_fmt, ...) PRINTF_ATTRIBUTE(3,4);
 449 struct ldb_dn_component *ldb_dn_get_rdn(void *mem_ctx, const struct ldb_dn *dn);
 450
 451 /* useful functions for ldb_message structure manipulation */
 452 int ldb_dn_cmp(struct ldb_context *ldb, const char *dn1, const char *dn2);
 453 int ldb_attr_cmp(const char *attr1, const char *attr2);
 454 int ldb_attr_dn(const char *attr);
 455 char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
 456
 457 /* create an empty message */
 458 struct ldb_message *ldb_msg_new(void *mem_ctx);
 459
 460 /* find an element within an message */
 461 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg,
 462                                                  const char *attr_name);
 463
 464 /* compare two ldb_val values - return 0 on match */
 465 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
 466
 467 /* find a value within an ldb_message_element */
 468 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el,
 469                                  struct ldb_val *val);
 470
 471 /* add a new empty element to a ldb_message */
 472 int ldb_msg_add_empty(struct ldb_message *msg, const char *attr_name, int flags);
 473
 474 /* add a element to a ldb_message */
 475 int ldb_msg_add(struct ldb_message *msg,
 476                 const struct ldb_message_element *el,
 477                 int flags);
 478 int ldb_msg_add_value(struct ldb_message *msg,
 479                       const char *attr_name,
 480                       const struct ldb_val *val);
 481 int ldb_msg_add_string(struct ldb_message *msg,
 482                        const char *attr_name, const char *str);
 483 int ldb_msg_add_fmt(struct ldb_message *msg,
 484                     const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
 485
 486 /* compare two message elements - return 0 on match */
 487 int ldb_msg_element_compare(struct ldb_message_element *el1,
 488                             struct ldb_message_element *el2);
 489
 490 /* find elements in a message and convert to a specific type, with
 491    a give default value if not found. Assumes that elements are
 492    single valued */
 493 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
 494 int ldb_msg_find_int(const struct ldb_message *msg,
 495                      const char *attr_name,
 496                      int default_value);
 497 unsigned int ldb_msg_find_uint(const struct ldb_message *msg,
 498                                const char *attr_name,
 499                                unsigned int default_value);
 500 int64_t ldb_msg_find_int64(const struct ldb_message *msg,
 501                            const char *attr_name,
 502                            int64_t default_value);
 503 uint64_t ldb_msg_find_uint64(const struct ldb_message *msg,
 504                              const char *attr_name,
 505                              uint64_t default_value);
 506 double ldb_msg_find_double(const struct ldb_message *msg,
 507                            const char *attr_name,
 508                            double default_value);
 509 const char *ldb_msg_find_string(const struct ldb_message *msg,
 510                                 const char *attr_name,
 511                                 const char *default_value);
 512
 513 void ldb_msg_sort_elements(struct ldb_message *msg);
 514
 515 struct ldb_message *ldb_msg_copy_shallow(void *mem_ctx,
 516                                          const struct ldb_message *msg);
 517 struct ldb_message *ldb_msg_copy(void *mem_ctx,
 518                                  const struct ldb_message *msg);
 519
 520 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb,
 521                                          const struct ldb_message *msg);
 522
 523
 524 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb,
 525                                  struct ldb_message *msg1,
 526                                  struct ldb_message *msg2);
 527
 528 int ldb_msg_sanity_check(const struct ldb_message *msg);
 529
 530 struct ldb_val ldb_val_dup(void *mem_ctx, const struct ldb_val *v);
 531
 532 /*
 533   this allows the user to set a debug function for error reporting
 534 */
 535 int ldb_set_debug(struct ldb_context *ldb,
 536                   void (*debug)(void *context, enum ldb_debug_level level,
 537                                 const char *fmt, va_list ap),
 538                   void *context);
 539
 540 /* this sets up debug to print messages on stderr */
 541 int ldb_set_debug_stderr(struct ldb_context *ldb);
 542
 543 /* control backend specific opaque values */
 544 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
 545 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
 546
 547 const struct ldb_attrib_handler *ldb_attrib_handler(struct ldb_context *ldb,
 548                                                     const char *attrib);
 549
 550
 551 const char **ldb_attr_list_copy(void *mem_ctx, const char * const *attrs);
 552 int ldb_attr_in_list(const char * const *attrs, const char *attr);
 553
 554
 555 void ldb_parse_tree_attr_replace(struct ldb_parse_tree *tree,
 556                                  const char *attr,
 557                                  const char *replace);
 558
 559 int ldb_msg_rename_attr(struct ldb_message *msg, const char *attr, const char *replace);
 560 int ldb_msg_copy_attr(struct ldb_message *msg, const char *attr, const char *replace);
 561 void ldb_msg_remove_attr(struct ldb_message *msg, const char *attr);
 562
 563 char *ldb_timestring(void *mem_ctx, time_t t);
 564 time_t ldb_string_to_time(const char *s);
 565
 566 char *ldb_dn_canonical_string(void *mem_ctx, const struct ldb_dn *dn);
 567 char *ldb_dn_canonical_ex_string(void *mem_ctx, const struct ldb_dn *dn);
 568 #endif