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 /* 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
  74
  75
  76 /*
  77   well known object IDs
  78 */
  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"
  81
  82 /*
  83   results are given back as arrays of ldb_message_element
  84 */
  85 struct ldb_message_element {
  86         unsigned int flags;
  87         const char *name;
  88         unsigned int num_values;
  89         struct ldb_val *values;
  90 };
  91
  92
  93 /*
  94   a ldb_message represents all or part of a record. It can contain an arbitrary
  95   number of elements.
  96 */
  97 struct ldb_message {
  98         char *dn;
  99         unsigned int num_elements;
 100         struct ldb_message_element *elements;
 101         void *private_data; /* private to the backend */
 102 };
 103
 104 enum ldb_changetype {
 105         LDB_CHANGETYPE_NONE=0,
 106         LDB_CHANGETYPE_ADD,
 107         LDB_CHANGETYPE_DELETE,
 108         LDB_CHANGETYPE_MODIFY
 109 };
 110
 111 /*
 112   a ldif record - from ldif_read
 113 */
 114 struct ldb_ldif {
 115         enum ldb_changetype changetype;
 116         struct ldb_message *msg;
 117 };
 118
 119 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
 120                 LDB_SCOPE_BASE=0,
 121                 LDB_SCOPE_ONELEVEL=1,
 122                 LDB_SCOPE_SUBTREE=2};
 123
 124 struct ldb_context;
 125
 126 /*
 127   the fuction type for the callback used in traversing the database
 128 */
 129 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
 130
 131
 132 struct ldb_module;
 133
 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};
 137
 138 /*
 139   the user can optionally supply a debug function. The function
 140   is based on the vfprintf() style of interface, but with the addition
 141   of a severity level
 142 */
 143 struct ldb_debug_ops {
 144         void (*debug)(void *context, enum ldb_debug_level level,
 145                       const char *fmt, va_list ap);
 146         void *context;
 147 };
 148
 149 #define LDB_FLG_RDONLY 1
 150
 151 #ifndef PRINTF_ATTRIBUTE
 152 #define PRINTF_ATTRIBUTE(a,b)
 153 #endif
 154
 155
 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='!'};
 160
 161 struct ldb_parse_tree {
 162         enum ldb_parse_op operation;
 163         union {
 164                 struct {
 165                         char *attr;
 166                         struct ldb_val value;
 167                 } simple;
 168                 struct {
 169                         char *attr;
 170                 } present;
 171                 struct {
 172                         char *attr;
 173                         int start_with_wildcard;
 174                         int end_with_wildcard;
 175                         struct ldb_val **chunks;
 176                 } substring;
 177                 struct {
 178                         char *attr;
 179                         int dnAttributes;
 180                         char *rule_id;
 181                         struct ldb_val value;
 182                 } extended;
 183                 struct {
 184                         unsigned int num_elements;
 185                         struct ldb_parse_tree **elements;
 186                 } list;
 187                 struct {
 188                         struct ldb_parse_tree *child;
 189                 } not;
 190         } u;
 191 };
 192
 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);
 196
 197
 198 /*
 199   functions for controlling attribute handling
 200 */
 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 *);
 203
 204 struct ldb_attrib_handler {
 205         const char *attr;
 206
 207         /* LDB_ATTR_FLAG_* */
 208         unsigned flags;
 209
 210         /* convert from ldif to binary format */
 211         ldb_attr_handler_t ldif_read_fn;
 212
 213         /* convert from binary to ldif format */
 214         ldb_attr_handler_t ldif_write_fn;
 215
 216         /* canonicalise a value, for use by indexing and dn construction */
 217         ldb_attr_handler_t canonicalise_fn;
 218
 219         /* compare two values */
 220         ldb_attr_comparison_t comparison_fn;
 221 };
 222
 223 #define LDB_ATTR_FLAG_HIDDEN     (1<<0)
 224
 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"
 231
 232 /*
 233   initialise a ldb context
 234 */
 235 struct ldb_context *ldb_init(void *mem_ctx);
 236
 237 /*
 238  connect to a database. The URL can either be one of the following forms
 239    ldb://path
 240    ldapi://path
 241
 242    flags is made up of LDB_FLG_*
 243
 244    the options are passed uninterpreted to the backend, and are
 245    backend specific
 246 */
 247 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
 248
 249 /*
 250   search the database given a LDAP-like search expression
 251
 252   return the number of records found, or -1 on error
 253
 254   use talloc_free to free the ldb_message returned
 255 */
 256 int ldb_search(struct ldb_context *ldb,
 257                const char *base,
 258                enum ldb_scope scope,
 259                const char *expression,
 260                const char * const *attrs, struct ldb_message ***res);
 261
 262 /*
 263   like ldb_search() but takes a parse tree
 264 */
 265 int ldb_search_bytree(struct ldb_context *ldb,
 266                       const char *base,
 267                       enum ldb_scope scope,
 268                       struct ldb_parse_tree *tree,
 269                       const char * const *attrs, struct ldb_message ***res);
 270
 271 /*
 272   add a record to the database. Will fail if a record with the given class and key
 273   already exists
 274 */
 275 int ldb_add(struct ldb_context *ldb,
 276             const struct ldb_message *message);
 277
 278 /*
 279   modify the specified attributes of a record
 280 */
 281 int ldb_modify(struct ldb_context *ldb,
 282                const struct ldb_message *message);
 283
 284 /*
 285   rename a record in the database
 286 */
 287 int ldb_rename(struct ldb_context *ldb, const char *olddn, const char *newdn);
 288
 289 /*
 290   create a named lock
 291 */
 292 int ldb_lock(struct ldb_context *ldb, const char *lockname);
 293
 294 /*
 295   release a named lock
 296 */
 297 int ldb_unlock(struct ldb_context *ldb, const char *lockname);
 298
 299 /*
 300   delete a record from the database
 301 */
 302 int ldb_delete(struct ldb_context *ldb, const char *dn);
 303
 304
 305 /*
 306   return extended error information from the last call
 307 */
 308 const char *ldb_errstring(struct ldb_context *ldb);
 309
 310 /*
 311   casefold a string (should be UTF8, but at the moment it isn't)
 312 */
 313 char *ldb_casefold(void *mem_ctx, const char *s);
 314 int ldb_caseless_cmp(const char *s1, const char *s2);
 315
 316 /*
 317   ldif manipulation functions
 318 */
 319 int ldb_ldif_write(struct ldb_context *ldb,
 320                    int (*fprintf_fn)(void *, const char *, ...),
 321                    void *private_data,
 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);
 334
 335
 336 /* useful functions for ldb_message structure manipulation */
 337
 338 int ldb_dn_cmp(const char *dn1, const char *dn2);
 339 int ldb_attr_cmp(const char *dn1, const char *dn2);
 340
 341 /* case-fold a DN */
 342 char *ldb_dn_fold(void * mem_ctx,
 343                   const char * dn,
 344                   void * user_data,
 345                   int (* case_fold_attr_fn)(void * user_data, char * attr));
 346
 347 /* create an empty message */
 348 struct ldb_message *ldb_msg_new(void *mem_ctx);
 349
 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);
 353
 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);
 356
 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);
 360
 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);
 364
 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,
 369                 int flags);
 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);
 378
 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);
 382
 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
 385    single valued */
 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,
 389                      int default_value);
 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);
 405
 406 void ldb_msg_sort_elements(struct ldb_message *msg);
 407
 408 void ldb_msg_free(struct ldb_context *ldb, struct ldb_message *msg);
 409
 410 struct ldb_message *ldb_msg_copy(struct ldb_context *ldb,
 411                                  const struct ldb_message *msg);
 412
 413 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb,
 414                                          const struct ldb_message *msg);
 415
 416
 417 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb,
 418                                  struct ldb_message *msg1,
 419                                  struct ldb_message *msg2);
 420
 421 struct ldb_val ldb_val_dup(void *mem_ctx, const struct ldb_val *v);
 422
 423 /*
 424   this allows the user to set a debug function for error reporting
 425 */
 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),
 429                   void *context);
 430
 431 /* this sets up debug to print messages on stderr */
 432 int ldb_set_debug_stderr(struct ldb_context *ldb);
 433
 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);
 437
 438 #endif