source/lib/ldb/include/ldb.h

   1 /*
   2    ldb database library
   3
   4    Copyright (C) Andrew Tridgell  2004
   5
   6      ** NOTE! The following LGPL license applies to the ldb
   7      ** library. This does NOT imply that all of Samba is released
   8      ** under the LGPL
   9
  10    This library is free software; you can redistribute it and/or
  11    modify it under the terms of the GNU Lesser General Public
  12    License as published by the Free Software Foundation; either
  13    version 2 of the License, or (at your option) any later version.
  14
  15    This library is distributed in the hope that it will be useful,
  16    but WITHOUT ANY WARRANTY; without even the implied warranty of
  17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18    Lesser General Public License for more details.
  19
  20    You should have received a copy of the GNU Lesser General Public
  21    License along with this library; if not, write to the Free Software
  22    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  23 */
  24
  25 /*
  26  *  Name: ldb
  27  *
  28  *  Component: ldb header
  29  *
  30  *  Description: defines for base ldb API
  31  *
  32  *  Author: Andrew Tridgell
  33  */
  34
  35 #ifndef _LDB_H_
  36 #define _LDB_H_ 1
  37
  38 /*
  39   major restrictions as compared to normal LDAP:
  40
  41      - no async calls.
  42      - each record must have a unique key field
  43      - the key must be representable as a NULL terminated C string and may not
  44        contain a comma or braces
  45
  46   major restrictions as compared to tdb:
  47
  48      - no explicit locking calls
  49
  50 */
  51
  52 /*
  53   an individual lump of data in a result comes in this format. The
  54   pointer will usually be to a UTF-8 string if the application is
  55   sensible, but it can be to anything you like, including binary data
  56   blobs of arbitrary size.
  57 */
  58 struct ldb_val {
  59         unsigned int length;
  60         void *data;
  61 };
  62
  63 /* these flags are used in ldd_message_element.flags fields. The
  64    LDA_FLAGS_MOD_* flags are used in ldap_modify() calls to specify
  65    whether attributes are being added, deleted or modified */
  66 #define LDB_FLAG_MOD_MASK  0x3
  67 #define LDB_FLAG_MOD_ADD     1
  68 #define LDB_FLAG_MOD_REPLACE 2
  69 #define LDB_FLAG_MOD_DELETE  3
  70
  71
  72 /*
  73   results are given back as arrays of ldb_message_element
  74 */
  75 struct ldb_message_element {
  76         unsigned int flags;
  77         char *name;
  78         unsigned int num_values;
  79         struct ldb_val *values;
  80 };
  81
  82
  83 /*
  84   a ldb_message represents all or part of a record. It can contain an arbitrary
  85   number of elements.
  86 */
  87 struct ldb_message {
  88         char *dn;
  89         unsigned int num_elements;
  90         struct ldb_message_element *elements;
  91         void *private_data; /* private to the backend */
  92 };
  93
  94 enum ldb_changetype {
  95         LDB_CHANGETYPE_NONE=0,
  96         LDB_CHANGETYPE_ADD,
  97         LDB_CHANGETYPE_DELETE,
  98         LDB_CHANGETYPE_MODIFY
  99 };
 100
 101 /*
 102   a ldif record - from ldif_read
 103 */
 104 struct ldb_ldif {
 105         enum ldb_changetype changetype;
 106         struct ldb_message msg;
 107 };
 108
 109 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
 110                 LDB_SCOPE_BASE=0,
 111                 LDB_SCOPE_ONELEVEL=1,
 112                 LDB_SCOPE_SUBTREE=2};
 113
 114 struct ldb_context;
 115
 116 /*
 117   the fuction type for the callback used in traversing the database
 118 */
 119 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
 120
 121
 122 /*
 123    these function pointers define the operations that a ldb backend must perform
 124    they correspond exactly to the ldb_*() interface
 125 */
 126 struct ldb_backend_ops {
 127         int (*close)(struct ldb_context *);
 128         int (*search)(struct ldb_context *, const char *, enum ldb_scope,
 129                       const char *, const char * const [], struct ldb_message ***);
 130         int (*search_free)(struct ldb_context *, struct ldb_message **);
 131         int (*add_record)(struct ldb_context *, const struct ldb_message *);
 132         int (*modify_record)(struct ldb_context *, const struct ldb_message *);
 133         int (*delete_record)(struct ldb_context *, const char *);
 134         const char * (*errstring)(struct ldb_context *);
 135
 136         /* this is called when the alloc ops changes to ensure we
 137            don't have any old allocated data in the context */
 138         void (*cache_free)(struct ldb_context *);
 139 };
 140
 141
 142 /*
 143   the user can optionally supply a allocator function. It is presumed
 144   it will act like a modern realloc(), with a context ptr to allow
 145   for pool allocators
 146 */
 147 struct ldb_alloc_ops {
 148         void *(*alloc)(void *context, void *ptr, size_t size);
 149         void *context;
 150 };
 151
 152 /* debugging uses one of the following levels */
 153 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR,
 154                       LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
 155
 156 /*
 157   the user can optionally supply a debug function. The function
 158   is based on the vfprintf() style of interface, but with the addition
 159   of a severity level
 160 */
 161 struct ldb_debug_ops {
 162         void (*debug)(void *context, enum ldb_debug_level level,
 163                       const char *fmt, va_list ap);
 164         void *context;
 165 };
 166
 167
 168 /*
 169   every ldb connection is started by establishing a ldb_context
 170 */
 171 struct ldb_context {
 172         /* a private pointer for the backend to use */
 173         void *private_data;
 174
 175         /* the operations provided by the backend */
 176         const struct ldb_backend_ops *ops;
 177
 178         /* memory allocation info */
 179         struct ldb_alloc_ops alloc_ops;
 180
 181         /* memory allocation info */
 182         struct ldb_debug_ops debug_ops;
 183 };
 184
 185
 186 #define LDB_FLG_RDONLY 1
 187
 188 /*
 189  connect to a database. The URL can either be one of the following forms
 190    ldb://path
 191    ldapi://path
 192
 193    flags is made up of LDB_FLG_*
 194
 195    the options are passed uninterpreted to the backend, and are
 196    backend specific
 197 */
 198 struct ldb_context *ldb_connect(const char *url, unsigned int flags,
 199                                 const char *options[]);
 200
 201 /*
 202   close the connection to the database
 203 */
 204 int ldb_close(struct ldb_context *ldb);
 205
 206
 207 /*
 208   search the database given a LDAP-like search expression
 209
 210   return the number of records found, or -1 on error
 211 */
 212 int ldb_search(struct ldb_context *ldb,
 213                const char *base,
 214                enum ldb_scope scope,
 215                const char *expression,
 216                const char * const *attrs, struct ldb_message ***res);
 217
 218 /*
 219    free a set of messages returned by ldb_search
 220 */
 221 int ldb_search_free(struct ldb_context *ldb, struct ldb_message **msgs);
 222
 223
 224 /*
 225   add a record to the database. Will fail if a record with the given class and key
 226   already exists
 227 */
 228 int ldb_add(struct ldb_context *ldb,
 229             const struct ldb_message *message);
 230
 231 /*
 232   modify the specified attributes of a record
 233 */
 234 int ldb_modify(struct ldb_context *ldb,
 235                const struct ldb_message *message);
 236
 237 /*
 238   delete a record from the database
 239 */
 240 int ldb_delete(struct ldb_context *ldb, const char *dn);
 241
 242
 243 /*
 244   return extended error information from the last call
 245 */
 246 const char *ldb_errstring(struct ldb_context *ldb);
 247
 248 /*
 249   casefold a string (should be UTF8, but at the moment it isn't)
 250 */
 251 char *ldb_casefold(struct ldb_context *ldb, const char *s);
 252
 253 /*
 254   ldif manipulation functions
 255 */
 256 int ldb_ldif_write(struct ldb_context *ldb,
 257                    int (*fprintf_fn)(void *, const char *, ...),
 258                    void *private_data,
 259                    const struct ldb_ldif *ldif);
 260 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *);
 261 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
 262                                int (*fgetc_fn)(void *), void *private_data);
 263 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
 264 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char *s);
 265 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
 266
 267
 268 /* useful functions for ldb_message structure manipulation */
 269
 270 /* find an element within an message */
 271 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg,
 272                                                  const char *attr_name);
 273
 274 /* compare two ldb_val values - return 0 on match */
 275 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
 276
 277 /* find a value within an ldb_message_element */
 278 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el,
 279                                  struct ldb_val *val);
 280
 281 /* add a new empty element to a ldb_message */
 282 int ldb_msg_add_empty(struct ldb_context *ldb,
 283                       struct ldb_message *msg, const char *attr_name, int flags);
 284
 285 /* add a element to a ldb_message */
 286 int ldb_msg_add(struct ldb_context *ldb,
 287                 struct ldb_message *msg,
 288                 const struct ldb_message_element *el,
 289                 int flags);
 290
 291 /* compare two message elements - return 0 on match */
 292 int ldb_msg_element_compare(struct ldb_message_element *el1,
 293                             struct ldb_message_element *el2);
 294
 295 /* find elements in a message and convert to a specific type, with
 296    a give default value if not found. Assumes that elements are
 297    single valued */
 298 int ldb_msg_find_int(const struct ldb_message *msg,
 299                      const char *attr_name,
 300                      int default_value);
 301 unsigned int ldb_msg_find_uint(const struct ldb_message *msg,
 302                                const char *attr_name,
 303                                unsigned int default_value);
 304 double ldb_msg_find_double(const struct ldb_message *msg,
 305                            const char *attr_name,
 306                            double default_value);
 307 const char *ldb_msg_find_string(const struct ldb_message *msg,
 308                                 const char *attr_name,
 309                                 const char *default_value);
 310
 311
 312 /*
 313   this allows the user to choose their own allocation function
 314   the allocation function should behave like a modern realloc()
 315   function, which means that:
 316      malloc(size)       == alloc(context, NULL, size)
 317      free(ptr)          == alloc(context, ptr, 0)
 318      realloc(ptr, size) == alloc(context, ptr, size)
 319   The context argument is provided to allow for pool based allocators,
 320   which often take a context argument
 321 */
 322 int ldb_set_alloc(struct ldb_context *ldb,
 323                   void *(*alloc)(void *context, void *ptr, size_t size),
 324                   void *context);
 325
 326 /*
 327   this allows the user to set a debug function for error reporting
 328 */
 329 int ldb_set_debug(struct ldb_context *ldb,
 330                   void (*debug)(void *context, enum ldb_debug_level level,
 331                                 const char *fmt, va_list ap),
 332                   void *context);
 333
 334 /* this sets up debug to print messages on stderr */
 335 int ldb_set_debug_stderr(struct ldb_context *ldb);
 336
 337
 338 /* these are used as type safe versions of the ldb allocation functions */
 339 #define ldb_malloc_p(ldb, type) (type *)ldb_malloc(ldb, sizeof(type))
 340 #define ldb_malloc_array_p(ldb, type, count) (type *)ldb_realloc_array(ldb, NULL, sizeof(type), count)
 341 #define ldb_realloc_p(ldb, p, type, count) (type *)ldb_realloc_array(ldb, p, sizeof(type), count)
 342
 343 #endif