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 struct ldb_val {
  61         unsigned int length;
  62         void *data;
  63 };
  64
  65 /* these flags are used in ldd_message_element.flags fields. The
  66    LDA_FLAGS_MOD_* flags are used in ldap_modify() calls to specify
  67    whether attributes are being added, deleted or modified */
  68 #define LDB_FLAG_MOD_MASK  0x3
  69 #define LDB_FLAG_MOD_ADD     1
  70 #define LDB_FLAG_MOD_REPLACE 2
  71 #define LDB_FLAG_MOD_DELETE  3
  72
  73
  74 /*
  75   well known object IDs
  76 */
  77 #define LDB_OID_COMPARATOR_AND  "1.2.840.113556.1.4.803"
  78 #define LDB_OID_COMPARATOR_OR   "1.2.840.113556.1.4.804"
  79
  80 /*
  81   results are given back as arrays of ldb_message_element
  82 */
  83 struct ldb_message_element {
  84         unsigned int flags;
  85         char *name;
  86         unsigned int num_values;
  87         struct ldb_val *values;
  88 };
  89
  90
  91 /*
  92   a ldb_message represents all or part of a record. It can contain an arbitrary
  93   number of elements.
  94 */
  95 struct ldb_message {
  96         char *dn;
  97         unsigned int num_elements;
  98         struct ldb_message_element *elements;
  99         void *private_data; /* private to the backend */
 100 };
 101
 102 enum ldb_changetype {
 103         LDB_CHANGETYPE_NONE=0,
 104         LDB_CHANGETYPE_ADD,
 105         LDB_CHANGETYPE_DELETE,
 106         LDB_CHANGETYPE_MODIFY
 107 };
 108
 109 /*
 110   a ldif record - from ldif_read
 111 */
 112 struct ldb_ldif {
 113         enum ldb_changetype changetype;
 114         struct ldb_message *msg;
 115 };
 116
 117 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
 118                 LDB_SCOPE_BASE=0,
 119                 LDB_SCOPE_ONELEVEL=1,
 120                 LDB_SCOPE_SUBTREE=2};
 121
 122 struct ldb_context;
 123
 124 /*
 125   the fuction type for the callback used in traversing the database
 126 */
 127 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
 128
 129
 130 struct ldb_module;
 131
 132 /* debugging uses one of the following levels */
 133 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR,
 134                       LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
 135
 136 /*
 137   the user can optionally supply a debug function. The function
 138   is based on the vfprintf() style of interface, but with the addition
 139   of a severity level
 140 */
 141 struct ldb_debug_ops {
 142         void (*debug)(void *context, enum ldb_debug_level level,
 143                       const char *fmt, va_list ap);
 144         void *context;
 145 };
 146
 147 #define LDB_FLG_RDONLY 1
 148
 149 #ifndef PRINTF_ATTRIBUTE
 150 #define PRINTF_ATTRIBUTE(a,b)
 151 #endif
 152
 153
 154 /* structues for ldb_parse_tree handling code */
 155 enum ldb_parse_op {LDB_OP_SIMPLE=1, LDB_OP_EXTENDED=2,
 156                    LDB_OP_AND='&', LDB_OP_OR='|', LDB_OP_NOT='!'};
 157
 158 struct ldb_parse_tree {
 159         enum ldb_parse_op operation;
 160         union {
 161                 struct {
 162                         char *attr;
 163                         struct ldb_val value;
 164                 } simple;
 165                 struct {
 166                         char *attr;
 167                         int dnAttributes;
 168                         char *rule_id;
 169                         struct ldb_val value;
 170                 } extended;
 171                 struct {
 172                         unsigned int num_elements;
 173                         struct ldb_parse_tree **elements;
 174                 } list;
 175                 struct {
 176                         struct ldb_parse_tree *child;
 177                 } not;
 178         } u;
 179 };
 180
 181 struct ldb_parse_tree *ldb_parse_tree(void *mem_ctx, const char *s);
 182 char *ldb_filter_from_tree(void *mem_ctx, struct ldb_parse_tree *tree);
 183 char *ldb_binary_encode(void *ctx, struct ldb_val val);
 184
 185
 186 /*
 187  connect to a database. The URL can either be one of the following forms
 188    ldb://path
 189    ldapi://path
 190
 191    flags is made up of LDB_FLG_*
 192
 193    the options are passed uninterpreted to the backend, and are
 194    backend specific
 195 */
 196 struct ldb_context *ldb_connect(const char *url, unsigned int flags,
 197                                 const char *options[]);
 198
 199 /*
 200   search the database given a LDAP-like search expression
 201
 202   return the number of records found, or -1 on error
 203
 204   use talloc_free to free the ldb_message returned
 205 */
 206 int ldb_search(struct ldb_context *ldb,
 207                const char *base,
 208                enum ldb_scope scope,
 209                const char *expression,
 210                const char * const *attrs, struct ldb_message ***res);
 211
 212 /*
 213   like ldb_search() but takes a parse tree
 214 */
 215 int ldb_search_bytree(struct ldb_context *ldb,
 216                       const char *base,
 217                       enum ldb_scope scope,
 218                       struct ldb_parse_tree *tree,
 219                       const char * const *attrs, struct ldb_message ***res);
 220
 221 /*
 222   add a record to the database. Will fail if a record with the given class and key
 223   already exists
 224 */
 225 int ldb_add(struct ldb_context *ldb,
 226             const struct ldb_message *message);
 227
 228 /*
 229   modify the specified attributes of a record
 230 */
 231 int ldb_modify(struct ldb_context *ldb,
 232                const struct ldb_message *message);
 233
 234 /*
 235   rename a record in the database
 236 */
 237 int ldb_rename(struct ldb_context *ldb, const char *olddn, const char *newdn);
 238
 239 /*
 240   delete a record from the database
 241 */
 242 int ldb_delete(struct ldb_context *ldb, const char *dn);
 243
 244
 245 /*
 246   return extended error information from the last call
 247 */
 248 const char *ldb_errstring(struct ldb_context *ldb);
 249
 250 /*
 251   casefold a string (should be UTF8, but at the moment it isn't)
 252 */
 253 char *ldb_casefold(void *mem_ctx, const char *s);
 254
 255 /*
 256   ldif manipulation functions
 257 */
 258 int ldb_ldif_write(struct ldb_context *ldb,
 259                    int (*fprintf_fn)(void *, const char *, ...),
 260                    void *private_data,
 261                    const struct ldb_ldif *ldif);
 262 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *);
 263 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
 264                                int (*fgetc_fn)(void *), void *private_data);
 265 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
 266 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char *s);
 267 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
 268
 269
 270 /* useful functions for ldb_message structure manipulation */
 271
 272 int ldb_dn_cmp(const char *dn1, const char *dn2);
 273 int ldb_attr_cmp(const char *dn1, const char *dn2);
 274
 275 /* case-fold a DN */
 276 char *ldb_dn_fold(struct ldb_module *module, const char *dn, int (*case_fold_attr_fn)(struct ldb_module * module, char * attr));
 277
 278 /* create an empty message */
 279 struct ldb_message *ldb_msg_new(void *mem_ctx);
 280
 281 /* find an element within an message */
 282 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg,
 283                                                  const char *attr_name);
 284
 285 /* compare two ldb_val values - return 0 on match */
 286 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
 287
 288 /* find a value within an ldb_message_element */
 289 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el,
 290                                  struct ldb_val *val);
 291
 292 /* add a new empty element to a ldb_message */
 293 int ldb_msg_add_empty(struct ldb_context *ldb,
 294                       struct ldb_message *msg, const char *attr_name, int flags);
 295
 296 /* add a element to a ldb_message */
 297 int ldb_msg_add(struct ldb_context *ldb,
 298                 struct ldb_message *msg,
 299                 const struct ldb_message_element *el,
 300                 int flags);
 301 int ldb_msg_add_value(struct ldb_context *ldb,
 302                       struct ldb_message *msg,
 303                       const char *attr_name,
 304                       const struct ldb_val *val);
 305 int ldb_msg_add_string(struct ldb_context *ldb, struct ldb_message *msg,
 306                        const char *attr_name, const char *str);
 307 int ldb_msg_add_fmt(struct ldb_context *ldb, struct ldb_message *msg,
 308                     const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(4,5);
 309
 310 /* compare two message elements - return 0 on match */
 311 int ldb_msg_element_compare(struct ldb_message_element *el1,
 312                             struct ldb_message_element *el2);
 313
 314 /* find elements in a message and convert to a specific type, with
 315    a give default value if not found. Assumes that elements are
 316    single valued */
 317 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
 318 int ldb_msg_find_int(const struct ldb_message *msg,
 319                      const char *attr_name,
 320                      int default_value);
 321 unsigned int ldb_msg_find_uint(const struct ldb_message *msg,
 322                                const char *attr_name,
 323                                unsigned int default_value);
 324 int64_t ldb_msg_find_int64(const struct ldb_message *msg,
 325                            const char *attr_name,
 326                            int64_t default_value);
 327 uint64_t ldb_msg_find_uint64(const struct ldb_message *msg,
 328                              const char *attr_name,
 329                              uint64_t default_value);
 330 double ldb_msg_find_double(const struct ldb_message *msg,
 331                            const char *attr_name,
 332                            double default_value);
 333 const char *ldb_msg_find_string(const struct ldb_message *msg,
 334                                 const char *attr_name,
 335                                 const char *default_value);
 336
 337 void ldb_msg_sort_elements(struct ldb_message *msg);
 338
 339 void ldb_msg_free(struct ldb_context *ldb, struct ldb_message *msg);
 340
 341 struct ldb_message *ldb_msg_copy(struct ldb_context *ldb,
 342                                  const struct ldb_message *msg);
 343
 344 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb,
 345                                          const struct ldb_message *msg);
 346
 347
 348 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb,
 349                                  struct ldb_message *msg1,
 350                                  struct ldb_message *msg2);
 351
 352 struct ldb_val ldb_val_dup(void *mem_ctx, const struct ldb_val *v);
 353
 354 /*
 355   this allows the user to set a debug function for error reporting
 356 */
 357 int ldb_set_debug(struct ldb_context *ldb,
 358                   void (*debug)(void *context, enum ldb_debug_level level,
 359                                 const char *fmt, va_list ap),
 360                   void *context);
 361
 362 /* this sets up debug to print messages on stderr */
 363 int ldb_set_debug_stderr(struct ldb_context *ldb);
 364
 365 #endif