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
  53 */
  54
  55 /*
  56   an individual lump of data in a result comes in this format. The
  57   pointer will usually be to a UTF-8 string if the application is
  58   sensible, but it can be to anything you like, including binary data
  59   blobs of arbitrary size.
  60 */
  61 #ifndef ldb_val
  62 struct ldb_val {
  63         uint8_t *data;
  64         size_t length;
  65 };
  66 #endif
  67
  68 /* internal ldb exploded dn structures */
  69 struct ldb_dn_component {
  70         char *name;
  71         struct ldb_val value;
  72 };
  73 struct ldb_dn {
  74         int comp_num;
  75         struct ldb_dn_component *components;
  76 };
  77
  78 /* these flags are used in ldd_message_element.flags fields. The
  79    LDA_FLAGS_MOD_* flags are used in ldap_modify() calls to specify
  80    whether attributes are being added, deleted or modified */
  81 #define LDB_FLAG_MOD_MASK  0x3
  82 #define LDB_FLAG_MOD_ADD     1
  83 #define LDB_FLAG_MOD_REPLACE 2
  84 #define LDB_FLAG_MOD_DELETE  3
  85
  86
  87 /*
  88   well known object IDs
  89 */
  90 #define LDB_OID_COMPARATOR_AND  "1.2.840.113556.1.4.803"
  91 #define LDB_OID_COMPARATOR_OR   "1.2.840.113556.1.4.804"
  92
  93 /*
  94   results are given back as arrays of ldb_message_element
  95 */
  96 struct ldb_message_element {
  97         unsigned int flags;
  98         const char *name;
  99         unsigned int num_values;
 100         struct ldb_val *values;
 101 };
 102
 103
 104 /*
 105   a ldb_message represents all or part of a record. It can contain an arbitrary
 106   number of elements.
 107 */
 108 struct ldb_message {
 109         struct ldb_dn *dn;
 110         unsigned int num_elements;
 111         struct ldb_message_element *elements;
 112         void *private_data; /* private to the backend */
 113 };
 114
 115 enum ldb_changetype {
 116         LDB_CHANGETYPE_NONE=0,
 117         LDB_CHANGETYPE_ADD,
 118         LDB_CHANGETYPE_DELETE,
 119         LDB_CHANGETYPE_MODIFY
 120 };
 121
 122 /*
 123   a ldif record - from ldif_read
 124 */
 125 struct ldb_ldif {
 126         enum ldb_changetype changetype;
 127         struct ldb_message *msg;
 128 };
 129
 130 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
 131                 LDB_SCOPE_BASE=0,
 132                 LDB_SCOPE_ONELEVEL=1,
 133                 LDB_SCOPE_SUBTREE=2};
 134
 135 struct ldb_context;
 136
 137 /*
 138   the fuction type for the callback used in traversing the database
 139 */
 140 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
 141
 142
 143 struct ldb_module;
 144
 145 /* debugging uses one of the following levels */
 146 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR,
 147                       LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
 148
 149 /*
 150   the user can optionally supply a debug function. The function
 151   is based on the vfprintf() style of interface, but with the addition
 152   of a severity level
 153 */
 154 struct ldb_debug_ops {
 155         void (*debug)(void *context, enum ldb_debug_level level,
 156                       const char *fmt, va_list ap);
 157         void *context;
 158 };
 159
 160 #define LDB_FLG_RDONLY 1
 161 #define LDB_FLG_NOSYNC 2
 162
 163 #ifndef PRINTF_ATTRIBUTE
 164 #define PRINTF_ATTRIBUTE(a,b)
 165 #endif
 166
 167 /* structures for ldb_parse_tree handling code */
 168 enum ldb_parse_op { LDB_OP_AND=1, LDB_OP_OR=2, LDB_OP_NOT=3,
 169                     LDB_OP_EQUALITY=4, LDB_OP_SUBSTRING=5,
 170                     LDB_OP_GREATER=6, LDB_OP_LESS=7, LDB_OP_PRESENT=8,
 171                     LDB_OP_APPROX=9, LDB_OP_EXTENDED=10 };
 172
 173 struct ldb_parse_tree {
 174         enum ldb_parse_op operation;
 175         union {
 176                 struct {
 177                         struct ldb_parse_tree *child;
 178                 } isnot;
 179                 struct {
 180                         char *attr;
 181                         struct ldb_val value;
 182                 } equality;
 183                 struct {
 184                         char *attr;
 185                         int start_with_wildcard;
 186                         int end_with_wildcard;
 187                         struct ldb_val **chunks;
 188                 } substring;
 189                 struct {
 190                         char *attr;
 191                 } present;
 192                 struct {
 193                         char *attr;
 194                         struct ldb_val value;
 195                 } comparison;
 196                 struct {
 197                         char *attr;
 198                         int dnAttributes;
 199                         char *rule_id;
 200                         struct ldb_val value;
 201                 } extended;
 202                 struct {
 203                         unsigned int num_elements;
 204                         struct ldb_parse_tree **elements;
 205                 } list;
 206         } u;
 207 };
 208
 209 struct ldb_parse_tree *ldb_parse_tree(void *mem_ctx, const char *s);
 210 char *ldb_filter_from_tree(void *mem_ctx, struct ldb_parse_tree *tree);
 211 char *ldb_binary_encode(void *ctx, struct ldb_val val);
 212
 213
 214 /*
 215   functions for controlling attribute handling
 216 */
 217 typedef int (*ldb_attr_handler_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, struct ldb_val *);
 218 typedef int (*ldb_attr_comparison_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, const struct ldb_val *);
 219
 220 struct ldb_attrib_handler {
 221         const char *attr;
 222
 223         /* LDB_ATTR_FLAG_* */
 224         unsigned flags;
 225
 226         /* convert from ldif to binary format */
 227         ldb_attr_handler_t ldif_read_fn;
 228
 229         /* convert from binary to ldif format */
 230         ldb_attr_handler_t ldif_write_fn;
 231
 232         /* canonicalise a value, for use by indexing and dn construction */
 233         ldb_attr_handler_t canonicalise_fn;
 234
 235         /* compare two values */
 236         ldb_attr_comparison_t comparison_fn;
 237 };
 238
 239 #define LDB_ATTR_FLAG_HIDDEN     (1<<0)
 240
 241 /* well-known ldap attribute syntaxes - see rfc2252 section 4.3.2 */
 242 #define LDB_SYNTAX_DN                   "1.3.6.1.4.1.1466.115.121.1.12"
 243 #define LDB_SYNTAX_DIRECTORY_STRING     "1.3.6.1.4.1.1466.115.121.1.15"
 244 #define LDB_SYNTAX_INTEGER              "1.3.6.1.4.1.1466.115.121.1.27"
 245 #define LDB_SYNTAX_OCTET_STRING         "1.3.6.1.4.1.1466.115.121.1.40"
 246 #define LDB_SYNTAX_OBJECTCLASS          "LDB_SYNTAX_OBJECTCLASS"
 247
 248 /*
 249   initialise a ldb context
 250 */
 251 struct ldb_context *ldb_init(void *mem_ctx);
 252
 253 /*
 254  connect to a database. The URL can either be one of the following forms
 255    ldb://path
 256    ldapi://path
 257
 258    flags is made up of LDB_FLG_*
 259
 260    the options are passed uninterpreted to the backend, and are
 261    backend specific
 262 */
 263 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
 264
 265 /*
 266   search the database given a LDAP-like search expression
 267
 268   return the number of records found, or -1 on error
 269
 270   use talloc_free to free the ldb_message returned
 271 */
 272 int ldb_search(struct ldb_context *ldb,
 273                const struct ldb_dn *base,
 274                enum ldb_scope scope,
 275                const char *expression,
 276                const char * const *attrs, struct ldb_message ***res);
 277
 278 /*
 279   like ldb_search() but takes a parse tree
 280 */
 281 int ldb_search_bytree(struct ldb_context *ldb,
 282                       const struct ldb_dn *base,
 283                       enum ldb_scope scope,
 284                       struct ldb_parse_tree *tree,
 285                       const char * const *attrs, struct ldb_message ***res);
 286
 287 /*
 288   add a record to the database. Will fail if a record with the given class and key
 289   already exists
 290 */
 291 int ldb_add(struct ldb_context *ldb,
 292             const struct ldb_message *message);
 293
 294 /*
 295   modify the specified attributes of a record
 296 */
 297 int ldb_modify(struct ldb_context *ldb,
 298                const struct ldb_message *message);
 299
 300 /*
 301   rename a record in the database
 302 */
 303 int ldb_rename(struct ldb_context *ldb, const struct ldb_dn *olddn, const struct ldb_dn *newdn);
 304
 305 /*
 306   create a named lock
 307 */
 308 int ldb_lock(struct ldb_context *ldb, const char *lockname);
 309
 310 /*
 311   release a named lock
 312 */
 313 int ldb_unlock(struct ldb_context *ldb, const char *lockname);
 314
 315 /*
 316   delete a record from the database
 317 */
 318 int ldb_delete(struct ldb_context *ldb, const struct ldb_dn *dn);
 319
 320
 321 /*
 322   return extended error information from the last call
 323 */
 324 const char *ldb_errstring(struct ldb_context *ldb);
 325
 326 /*
 327   casefold a string (should be UTF8, but at the moment it isn't)
 328 */
 329 char *ldb_casefold(void *mem_ctx, const char *s);
 330 int ldb_caseless_cmp(const char *s1, const char *s2);
 331
 332 /*
 333   ldif manipulation functions
 334 */
 335 int ldb_ldif_write(struct ldb_context *ldb,
 336                    int (*fprintf_fn)(void *, const char *, ...),
 337                    void *private_data,
 338                    const struct ldb_ldif *ldif);
 339 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *);
 340 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
 341                                int (*fgetc_fn)(void *), void *private_data);
 342 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
 343 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
 344 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
 345 char *ldb_base64_encode(void *mem_ctx, const char *buf, int len);
 346 int ldb_base64_decode(char *s);
 347 int ldb_attrib_add_handlers(struct ldb_context *ldb,
 348                             const struct ldb_attrib_handler *handlers,
 349                             unsigned num_handlers);
 350
 351 /* The following definitions come from lib/ldb/common/ldb_dn.c  */
 352
 353 int ldb_dn_is_special(const struct ldb_dn *dn);
 354 int ldb_dn_check_special(const struct ldb_dn *dn, const char *check);
 355 char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
 356 struct ldb_dn *ldb_dn_new(void *mem_ctx);
 357 struct ldb_dn *ldb_dn_explode(void *mem_ctx, const char *dn);
 358 char *ldb_dn_linearize(void *mem_ctx, const struct ldb_dn *edn);
 359 char *ldb_dn_linearize_casefold(struct ldb_context *ldb, const struct ldb_dn *edn);
 360 int ldb_dn_compare_base(struct ldb_context *ldb, const struct ldb_dn *base, const struct ldb_dn *dn);
 361 int ldb_dn_compare(struct ldb_context *ldb, const struct ldb_dn *edn0, const struct ldb_dn *edn1);
 362 struct ldb_dn *ldb_dn_casefold(struct ldb_context *ldb, const struct ldb_dn *edn);
 363 struct ldb_dn *ldb_dn_explode_casefold(struct ldb_context *ldb, const char *dn);
 364 struct ldb_dn *ldb_dn_copy_partial(void *mem_ctx, const struct ldb_dn *dn, int num_el);
 365 struct ldb_dn *ldb_dn_copy(void *mem_ctx, const struct ldb_dn *dn);
 366 struct ldb_dn *ldb_dn_get_parent(void *mem_ctx, const struct ldb_dn *dn);
 367 struct ldb_dn_component *ldb_dn_build_component(void *mem_ctx, const char *attr,
 368                                                                const char *val);
 369 struct ldb_dn *ldb_dn_build_child(void *mem_ctx, const char *attr,
 370                                                  const char * value,
 371                                                  const struct ldb_dn *base);
 372 struct ldb_dn *ldb_dn_make_child(void *mem_ctx,
 373                                  const struct ldb_dn_component *component,
 374                                  const struct ldb_dn *base);
 375 struct ldb_dn *ldb_dn_compose(void *mem_ctx, const struct ldb_dn *dn1, const struct ldb_dn *dn2);
 376 struct ldb_dn *ldb_dn_string_compose(void *mem_ctx, const struct ldb_dn *base, const char *child_fmt, ...);
 377 struct ldb_dn_component *ldb_dn_get_rdn(void *mem_ctx, const struct ldb_dn *dn);
 378
 379 /* useful functions for ldb_message structure manipulation */
 380 int ldb_dn_cmp(struct ldb_context *ldb, const char *dn1, const char *dn2);
 381 int ldb_attr_cmp(const char *dn1, const char *dn2);
 382 char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
 383
 384 /* create an empty message */
 385 struct ldb_message *ldb_msg_new(void *mem_ctx);
 386
 387 /* find an element within an message */
 388 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg,
 389                                                  const char *attr_name);
 390
 391 /* compare two ldb_val values - return 0 on match */
 392 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
 393
 394 /* find a value within an ldb_message_element */
 395 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el,
 396                                  struct ldb_val *val);
 397
 398 /* add a new empty element to a ldb_message */
 399 int ldb_msg_add_empty(struct ldb_context *ldb,
 400                       struct ldb_message *msg, const char *attr_name, int flags);
 401
 402 /* add a element to a ldb_message */
 403 int ldb_msg_add(struct ldb_context *ldb,
 404                 struct ldb_message *msg,
 405                 const struct ldb_message_element *el,
 406                 int flags);
 407 int ldb_msg_add_value(struct ldb_context *ldb,
 408                       struct ldb_message *msg,
 409                       const char *attr_name,
 410                       const struct ldb_val *val);
 411 int ldb_msg_add_string(struct ldb_context *ldb, struct ldb_message *msg,
 412                        const char *attr_name, const char *str);
 413 int ldb_msg_add_fmt(struct ldb_context *ldb, struct ldb_message *msg,
 414                     const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(4,5);
 415
 416 /* compare two message elements - return 0 on match */
 417 int ldb_msg_element_compare(struct ldb_message_element *el1,
 418                             struct ldb_message_element *el2);
 419
 420 /* find elements in a message and convert to a specific type, with
 421    a give default value if not found. Assumes that elements are
 422    single valued */
 423 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
 424 int ldb_msg_find_int(const struct ldb_message *msg,
 425                      const char *attr_name,
 426                      int default_value);
 427 unsigned int ldb_msg_find_uint(const struct ldb_message *msg,
 428                                const char *attr_name,
 429                                unsigned int default_value);
 430 int64_t ldb_msg_find_int64(const struct ldb_message *msg,
 431                            const char *attr_name,
 432                            int64_t default_value);
 433 uint64_t ldb_msg_find_uint64(const struct ldb_message *msg,
 434                              const char *attr_name,
 435                              uint64_t default_value);
 436 double ldb_msg_find_double(const struct ldb_message *msg,
 437                            const char *attr_name,
 438                            double default_value);
 439 const char *ldb_msg_find_string(const struct ldb_message *msg,
 440                                 const char *attr_name,
 441                                 const char *default_value);
 442
 443 void ldb_msg_sort_elements(struct ldb_message *msg);
 444
 445 struct ldb_message *ldb_msg_copy(void *mem_ctx,
 446                                  const struct ldb_message *msg);
 447
 448 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb,
 449                                          const struct ldb_message *msg);
 450
 451
 452 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb,
 453                                  struct ldb_message *msg1,
 454                                  struct ldb_message *msg2);
 455
 456 int ldb_msg_sanity_check(const struct ldb_message *msg);
 457
 458 struct ldb_val ldb_val_dup(void *mem_ctx, const struct ldb_val *v);
 459
 460 /*
 461   this allows the user to set a debug function for error reporting
 462 */
 463 int ldb_set_debug(struct ldb_context *ldb,
 464                   void (*debug)(void *context, enum ldb_debug_level level,
 465                                 const char *fmt, va_list ap),
 466                   void *context);
 467
 468 /* this sets up debug to print messages on stderr */
 469 int ldb_set_debug_stderr(struct ldb_context *ldb);
 470
 471 /* control backend specific opaque values */
 472 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
 473 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
 474
 475 const struct ldb_attrib_handler *ldb_attrib_handler(struct ldb_context *ldb,
 476                                                     const char *attrib);
 477
 478 #endif