source4/lib/ldb/include/ldb.h

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