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 /*
  36   major restrictions as compared to normal LDAP:
  37
  38      - no async calls.
  39      - each record must have a unique key field
  40      - the key must be representable as a NULL terminated C string and may not
  41        contain a comma or braces
  42
  43   major restrictions as compared to tdb:
  44
  45      - no explicit locking calls
  46
  47 */
  48
  49
  50 /*
  51   an individual lump of data in a result comes in this format. The
  52   pointer will usually be to a UTF-8 string if the application is
  53   sensible, but it can be to anything you like, including binary data
  54   blobs of arbitrary size.
  55 */
  56 struct ldb_val {
  57         unsigned int length;
  58         void *data;
  59 };
  60
  61 /* these flags are used in ldd_message_element.flags fields. The
  62    LDA_FLAGS_MOD_* flags are used in ldap_modify() calls to specify
  63    whether attributes are being added, deleted or modified */
  64 #define LDB_FLAG_MOD_MASK  0x3
  65 #define LDB_FLAG_MOD_ADD     1
  66 #define LDB_FLAG_MOD_REPLACE 2
  67 #define LDB_FLAG_MOD_DELETE  3
  68
  69
  70 /*
  71   results are given back as arrays of ldb_message_element
  72 */
  73 struct ldb_message_element {
  74         unsigned int flags;
  75         char *name;
  76         unsigned int num_values;
  77         struct ldb_val *values;
  78 };
  79
  80
  81 /*
  82   a ldb_message represents all or part of a record. It can contain an arbitrary
  83   number of elements.
  84 */
  85 struct ldb_message {
  86         char *dn;
  87         unsigned int num_elements;
  88         struct ldb_message_element *elements;
  89         void *private; /* private to the backend */
  90 };
  91
  92 enum ldb_changetype {
  93         LDB_CHANGETYPE_NONE=0,
  94         LDB_CHANGETYPE_ADD,
  95         LDB_CHANGETYPE_DELETE,
  96         LDB_CHANGETYPE_MODIFY
  97 };
  98
  99 /*
 100   a ldif record - from ldif_read
 101 */
 102 struct ldb_ldif {
 103         enum ldb_changetype changetype;
 104         struct ldb_message msg;
 105 };
 106
 107 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
 108                 LDB_SCOPE_BASE=0,
 109                 LDB_SCOPE_ONELEVEL=1,
 110                 LDB_SCOPE_SUBTREE=2};
 111
 112 struct ldb_context;
 113
 114 /*
 115   the fuction type for the callback used in traversing the database
 116 */
 117 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
 118
 119
 120 /*
 121    these function pointers define the operations that a ldb backend must perform
 122    they correspond exactly to the ldb_*() interface
 123 */
 124 struct ldb_backend_ops {
 125         int (*close)(struct ldb_context *);
 126         int (*search)(struct ldb_context *, const char *, enum ldb_scope,
 127                       const char *, const char *[], struct ldb_message ***);
 128         int (*search_free)(struct ldb_context *, struct ldb_message **);
 129         int (*add)(struct ldb_context *, const struct ldb_message *);
 130         int (*modify)(struct ldb_context *, const struct ldb_message *);
 131         int (*delete)(struct ldb_context *, const char *);
 132         const char * (*errstring)(struct ldb_context *);
 133 };
 134
 135 /*
 136   every ldb connection is started by establishing a ldb_context
 137 */
 138 struct ldb_context {
 139         /* a private pointer for the backend to use */
 140         void *private;
 141
 142         /* the operations provided by the backend */
 143         const struct ldb_backend_ops *ops;
 144 };
 145
 146
 147 #define LDB_FLG_RDONLY 1
 148
 149 /*
 150  connect to a database. The URL can either be one of the following forms
 151    ldb://path
 152    ldapi://path
 153
 154    flags is made up of LDB_FLG_*
 155
 156    the options are passed uninterpreted to the backend, and are
 157    backend specific
 158 */
 159 struct ldb_context *ldb_connect(const char *url, unsigned int flags,
 160                                 const char *options[]);
 161
 162 /*
 163   close the connection to the database
 164 */
 165 int ldb_close(struct ldb_context *ldb);
 166
 167
 168 /*
 169   search the database given a LDAP-like search expression
 170
 171   return the number of records found, or -1 on error
 172 */
 173 int ldb_search(struct ldb_context *ldb,
 174                const char *base,
 175                enum ldb_scope scope,
 176                const char *expression,
 177                char * const attrs[], struct ldb_message ***res);
 178
 179 /*
 180    free a set of messages returned by ldb_search
 181 */
 182 int ldb_search_free(struct ldb_context *ldb, struct ldb_message **msgs);
 183
 184
 185 /*
 186   add a record to the database. Will fail if a record with the given class and key
 187   already exists
 188 */
 189 int ldb_add(struct ldb_context *ldb,
 190             const struct ldb_message *message);
 191
 192 /*
 193   modify the specified attributes of a record
 194 */
 195 int ldb_modify(struct ldb_context *ldb,
 196                const struct ldb_message *message);
 197
 198 /*
 199   delete a record from the database
 200 */
 201 int ldb_delete(struct ldb_context *ldb, const char *dn);
 202
 203
 204 /*
 205   return extended error information from the last call
 206 */
 207 const char *ldb_errstring(struct ldb_context *ldb);
 208
 209 /*
 210   ldif manipulation functions
 211 */
 212 int ldif_write(int (*fprintf_fn)(void *, const char *, ...),
 213                void *private,
 214                const struct ldb_ldif *ldif);
 215 void ldif_read_free(struct ldb_ldif *);
 216 struct ldb_ldif *ldif_read(int (*fgetc_fn)(void *), void *private);
 217 struct ldb_ldif *ldif_read_file(FILE *f);
 218 struct ldb_ldif *ldif_read_string(const char *s);
 219 int ldif_write_file(FILE *f, const struct ldb_ldif *msg);