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   results are given back as arrays of ldb_message_element
  76 */
  77 struct ldb_message_element {
  78         unsigned int flags;
  79         char *name;
  80         unsigned int num_values;
  81         struct ldb_val *values;
  82 };
  83
  84
  85 /*
  86   a ldb_message represents all or part of a record. It can contain an arbitrary
  87   number of elements.
  88 */
  89 struct ldb_message {
  90         char *dn;
  91         unsigned int num_elements;
  92         struct ldb_message_element *elements;
  93         void *private_data; /* private to the backend */
  94 };
  95
  96 enum ldb_changetype {
  97         LDB_CHANGETYPE_NONE=0,
  98         LDB_CHANGETYPE_ADD,
  99         LDB_CHANGETYPE_DELETE,
 100         LDB_CHANGETYPE_MODIFY
 101 };
 102
 103 /*
 104   a ldif record - from ldif_read
 105 */
 106 struct ldb_ldif {
 107         enum ldb_changetype changetype;
 108         struct ldb_message msg;
 109 };
 110
 111 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
 112                 LDB_SCOPE_BASE=0,
 113                 LDB_SCOPE_ONELEVEL=1,
 114                 LDB_SCOPE_SUBTREE=2};
 115
 116 struct ldb_context;
 117
 118 /*
 119   the fuction type for the callback used in traversing the database
 120 */
 121 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
 122
 123
 124 struct ldb_module_ops;
 125
 126 /* basic module structure */
 127 struct ldb_module {
 128         struct ldb_module *prev, *next;
 129         struct ldb_context *ldb;
 130         void *private_data;
 131         const struct ldb_module_ops *ops;
 132 };
 133
 134 /*
 135    these function pointers define the operations that a ldb module must perform
 136    they correspond exactly to the ldb_*() interface
 137 */
 138 struct ldb_module_ops {
 139         const char *name;
 140         int (*close)(struct ldb_module *);
 141         int (*search)(struct ldb_module *, const char *, enum ldb_scope,
 142                       const char *, const char * const [], struct ldb_message ***);
 143         int (*search_free)(struct ldb_module *, struct ldb_message **);
 144         int (*add_record)(struct ldb_module *, const struct ldb_message *);
 145         int (*modify_record)(struct ldb_module *, const struct ldb_message *);
 146         int (*delete_record)(struct ldb_module *, const char *);
 147         int (*rename_record)(struct ldb_module *, const char *, const char *);
 148         const char * (*errstring)(struct ldb_module *);
 149
 150         /* this is called when the alloc ops changes to ensure we
 151            don't have any old allocated data in the context */
 152         void (*cache_free)(struct ldb_module *);
 153 };
 154
 155 /* the modules init function */
 156 typedef struct ldb_module *(*init_ldb_module_function)(void);
 157
 158 /*
 159   the user can optionally supply a allocator function. It is presumed
 160   it will act like a modern realloc(), with a context ptr to allow
 161   for pool allocators
 162 */
 163 struct ldb_alloc_ops {
 164         void *(*alloc)(const void *context, void *ptr, size_t size);
 165         void *context;
 166 };
 167
 168 /* debugging uses one of the following levels */
 169 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR,
 170                       LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
 171
 172 /*
 173   the user can optionally supply a debug function. The function
 174   is based on the vfprintf() style of interface, but with the addition
 175   of a severity level
 176 */
 177 struct ldb_debug_ops {
 178         void (*debug)(void *context, enum ldb_debug_level level,
 179                       const char *fmt, va_list ap);
 180         void *context;
 181 };
 182
 183
 184 /*
 185   every ldb connection is started by establishing a ldb_context
 186 */
 187 struct ldb_context {
 188         /* the operations provided by the backend */
 189         struct ldb_module *modules;
 190
 191         /* memory allocation info */
 192         struct ldb_alloc_ops alloc_ops;
 193
 194         /* memory allocation info */
 195         struct ldb_debug_ops debug_ops;
 196 };
 197
 198
 199 #define LDB_FLG_RDONLY 1
 200
 201 /*
 202  connect to a database. The URL can either be one of the following forms
 203    ldb://path
 204    ldapi://path
 205
 206    flags is made up of LDB_FLG_*
 207
 208    the options are passed uninterpreted to the backend, and are
 209    backend specific
 210 */
 211 struct ldb_context *ldb_connect(const char *url, unsigned int flags,
 212                                 const char *options[]);
 213
 214 /*
 215   close the connection to the database
 216 */
 217 int ldb_close(struct ldb_context *ldb);
 218
 219
 220 /*
 221   search the database given a LDAP-like search expression
 222
 223   return the number of records found, or -1 on error
 224 */
 225 int ldb_search(struct ldb_context *ldb,
 226                const char *base,
 227                enum ldb_scope scope,
 228                const char *expression,
 229                const char * const *attrs, struct ldb_message ***res);
 230
 231 /*
 232    free a set of messages returned by ldb_search
 233 */
 234 int ldb_search_free(struct ldb_context *ldb, struct ldb_message **msgs);
 235
 236
 237 /*
 238   add a record to the database. Will fail if a record with the given class and key
 239   already exists
 240 */
 241 int ldb_add(struct ldb_context *ldb,
 242             const struct ldb_message *message);
 243
 244 /*
 245   modify the specified attributes of a record
 246 */
 247 int ldb_modify(struct ldb_context *ldb,
 248                const struct ldb_message *message);
 249
 250 /*
 251   rename a record in the database
 252 */
 253 int ldb_rename(struct ldb_context *ldb, const char *olddn, const char *newdn);
 254
 255 /*
 256   delete a record from the database
 257 */
 258 int ldb_delete(struct ldb_context *ldb, const char *dn);
 259
 260
 261 /*
 262   return extended error information from the last call
 263 */
 264 const char *ldb_errstring(struct ldb_context *ldb);
 265
 266 /*
 267   casefold a string (should be UTF8, but at the moment it isn't)
 268 */
 269 char *ldb_casefold(struct ldb_context *ldb, const char *s);
 270
 271 /*
 272   ldif manipulation functions
 273 */
 274 int ldb_ldif_write(struct ldb_context *ldb,
 275                    int (*fprintf_fn)(void *, const char *, ...),
 276                    void *private_data,
 277                    const struct ldb_ldif *ldif);
 278 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *);
 279 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
 280                                int (*fgetc_fn)(void *), void *private_data);
 281 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
 282 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char *s);
 283 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
 284
 285
 286 /* useful functions for ldb_message structure manipulation */
 287
 288 /* find an element within an message */
 289 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg,
 290                                                  const char *attr_name);
 291
 292 /* compare two ldb_val values - return 0 on match */
 293 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
 294
 295 /* find a value within an ldb_message_element */
 296 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el,
 297                                  struct ldb_val *val);
 298
 299 /* add a new empty element to a ldb_message */
 300 int ldb_msg_add_empty(struct ldb_context *ldb,
 301                       struct ldb_message *msg, const char *attr_name, int flags);
 302
 303 /* add a element to a ldb_message */
 304 int ldb_msg_add(struct ldb_context *ldb,
 305                 struct ldb_message *msg,
 306                 const struct ldb_message_element *el,
 307                 int flags);
 308
 309 /* compare two message elements - return 0 on match */
 310 int ldb_msg_element_compare(struct ldb_message_element *el1,
 311                             struct ldb_message_element *el2);
 312
 313 /* find elements in a message and convert to a specific type, with
 314    a give default value if not found. Assumes that elements are
 315    single valued */
 316 int ldb_msg_find_int(const struct ldb_message *msg,
 317                      const char *attr_name,
 318                      int default_value);
 319 unsigned int ldb_msg_find_uint(const struct ldb_message *msg,
 320                                const char *attr_name,
 321                                unsigned int default_value);
 322 double ldb_msg_find_double(const struct ldb_message *msg,
 323                            const char *attr_name,
 324                            double default_value);
 325 const char *ldb_msg_find_string(const struct ldb_message *msg,
 326                                 const char *attr_name,
 327                                 const char *default_value);
 328
 329
 330 /*
 331   this allows the user to choose their own allocation function
 332   the allocation function should behave like a modern realloc()
 333   function, which means that:
 334      malloc(size)       == alloc(context, NULL, size)
 335      free(ptr)          == alloc(context, ptr, 0)
 336      realloc(ptr, size) == alloc(context, ptr, size)
 337   The context argument is provided to allow for pool based allocators,
 338   which often take a context argument
 339 */
 340 int ldb_set_alloc(struct ldb_context *ldb,
 341                   void *(*alloc)(const void *context, void *ptr, size_t size),
 342                   void *context);
 343
 344 /*
 345   this allows the user to set a debug function for error reporting
 346 */
 347 int ldb_set_debug(struct ldb_context *ldb,
 348                   void (*debug)(void *context, enum ldb_debug_level level,
 349                                 const char *fmt, va_list ap),
 350                   void *context);
 351
 352 /* this sets up debug to print messages on stderr */
 353 int ldb_set_debug_stderr(struct ldb_context *ldb);
 354
 355
 356 /* these are used as type safe versions of the ldb allocation functions */
 357 #define ldb_malloc_p(ldb, type) (type *)ldb_malloc(ldb, sizeof(type))
 358 #define ldb_malloc_array_p(ldb, type, count) (type *)ldb_realloc_array(ldb, NULL, sizeof(type), count)
 359 #define ldb_realloc_p(ldb, p, type, count) (type *)ldb_realloc_array(ldb, p, sizeof(type), count)
 360
 361 #endif