4 Copyright (C) Andrew Tridgell 2004
6 ** NOTE! The following LGPL license applies to the ldb
7 ** library. This does NOT imply that all of Samba is released
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.
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.
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
28 * Component: ldb header
30 * Description: defines for base ldb API
32 * Author: Andrew Tridgell
36 major restrictions as compared to normal LDAP:
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
43 major restrictions as compared to tdb:
45 - no explicit locking calls
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.
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
71 results are given back as arrays of ldb_message_element
73 struct ldb_message_element {
76 unsigned int num_values;
77 struct ldb_val *values;
82 a ldb_message represents all or part of a record. It can contain an arbitrary
87 unsigned int num_elements;
88 struct ldb_message_element *elements;
89 void *private_data; /* private to the backend */
93 LDB_CHANGETYPE_NONE=0,
95 LDB_CHANGETYPE_DELETE,
100 a ldif record - from ldif_read
103 enum ldb_changetype changetype;
104 struct ldb_message msg;
107 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
109 LDB_SCOPE_ONELEVEL=1,
110 LDB_SCOPE_SUBTREE=2};
115 the fuction type for the callback used in traversing the database
117 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
121 these function pointers define the operations that a ldb backend must perform
122 they correspond exactly to the ldb_*() interface
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 * const [], struct ldb_message ***);
128 int (*search_free)(struct ldb_context *, struct ldb_message **);
129 int (*add_record)(struct ldb_context *, const struct ldb_message *);
130 int (*modify_record)(struct ldb_context *, const struct ldb_message *);
131 int (*delete_record)(struct ldb_context *, const char *);
132 const char * (*errstring)(struct ldb_context *);
136 every ldb connection is started by establishing a ldb_context
139 /* a private pointer for the backend to use */
142 /* the operations provided by the backend */
143 const struct ldb_backend_ops *ops;
147 #define LDB_FLG_RDONLY 1
150 connect to a database. The URL can either be one of the following forms
154 flags is made up of LDB_FLG_*
156 the options are passed uninterpreted to the backend, and are
159 struct ldb_context *ldb_connect(const char *url, unsigned int flags,
160 const char *options[]);
163 close the connection to the database
165 int ldb_close(struct ldb_context *ldb);
169 search the database given a LDAP-like search expression
171 return the number of records found, or -1 on error
173 int ldb_search(struct ldb_context *ldb,
175 enum ldb_scope scope,
176 const char *expression,
177 const char * const *attrs, struct ldb_message ***res);
180 free a set of messages returned by ldb_search
182 int ldb_search_free(struct ldb_context *ldb, struct ldb_message **msgs);
186 add a record to the database. Will fail if a record with the given class and key
189 int ldb_add(struct ldb_context *ldb,
190 const struct ldb_message *message);
193 modify the specified attributes of a record
195 int ldb_modify(struct ldb_context *ldb,
196 const struct ldb_message *message);
199 delete a record from the database
201 int ldb_delete(struct ldb_context *ldb, const char *dn);
205 return extended error information from the last call
207 const char *ldb_errstring(struct ldb_context *ldb);
210 casefold a string (should be UTF8, but at the moment it isn't)
212 char *ldb_casefold(const char *s);
215 ldif manipulation functions
217 int ldif_write(int (*fprintf_fn)(void *, const char *, ...),
219 const struct ldb_ldif *ldif);
220 void ldif_read_free(struct ldb_ldif *);
221 struct ldb_ldif *ldif_read(int (*fgetc_fn)(void *), void *private_data);
222 struct ldb_ldif *ldif_read_file(FILE *f);
223 struct ldb_ldif *ldif_read_string(const char *s);
224 int ldif_write_file(FILE *f, const struct ldb_ldif *msg);