4 Copyright (C) Andrew Tridgell 2004
5 Copyright (C) Stefan Metzmacher 2004
7 ** NOTE! The following LGPL license applies to the ldb
8 ** library. This does NOT imply that all of Samba is released
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.
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.
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
29 * Component: ldb header
31 * Description: defines for base ldb API
33 * Author: Andrew Tridgell
34 * Author: Stefan Metzmacher
41 major restrictions as compared to normal LDAP:
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
48 major restrictions as compared to tdb:
50 - no explicit locking calls
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.
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
75 results are given back as arrays of ldb_message_element
77 struct ldb_message_element
{
80 unsigned int num_values
;
81 struct ldb_val
*values
;
86 a ldb_message represents all or part of a record. It can contain an arbitrary
91 unsigned int num_elements
;
92 struct ldb_message_element
*elements
;
93 void *private_data
; /* private to the backend */
97 LDB_CHANGETYPE_NONE
=0,
99 LDB_CHANGETYPE_DELETE
,
100 LDB_CHANGETYPE_MODIFY
104 a ldif record - from ldif_read
107 enum ldb_changetype changetype
;
108 struct ldb_message
*msg
;
111 enum ldb_scope
{LDB_SCOPE_DEFAULT
=-1,
113 LDB_SCOPE_ONELEVEL
=1,
114 LDB_SCOPE_SUBTREE
=2};
119 the fuction type for the callback used in traversing the database
121 typedef int (*ldb_traverse_fn
)(struct ldb_context
*, const struct ldb_message
*);
126 /* debugging uses one of the following levels */
127 enum ldb_debug_level
{LDB_DEBUG_FATAL
, LDB_DEBUG_ERROR
,
128 LDB_DEBUG_WARNING
, LDB_DEBUG_TRACE
};
131 the user can optionally supply a debug function. The function
132 is based on the vfprintf() style of interface, but with the addition
135 struct ldb_debug_ops
{
136 void (*debug
)(void *context
, enum ldb_debug_level level
,
137 const char *fmt
, va_list ap
);
141 #define LDB_FLG_RDONLY 1
143 #ifndef PRINTF_ATTRIBUTE
144 #define PRINTF_ATTRIBUTE(a,b)
149 connect to a database. The URL can either be one of the following forms
153 flags is made up of LDB_FLG_*
155 the options are passed uninterpreted to the backend, and are
158 struct ldb_context
*ldb_connect(const char *url
, unsigned int flags
,
159 const char *options
[]);
162 search the database given a LDAP-like search expression
164 return the number of records found, or -1 on error
166 use talloc_free to free the ldb_message returned
168 int ldb_search(struct ldb_context
*ldb
,
170 enum ldb_scope scope
,
171 const char *expression
,
172 const char * const *attrs
, struct ldb_message
***res
);
175 add a record to the database. Will fail if a record with the given class and key
178 int ldb_add(struct ldb_context
*ldb
,
179 const struct ldb_message
*message
);
182 modify the specified attributes of a record
184 int ldb_modify(struct ldb_context
*ldb
,
185 const struct ldb_message
*message
);
188 rename a record in the database
190 int ldb_rename(struct ldb_context
*ldb
, const char *olddn
, const char *newdn
);
193 delete a record from the database
195 int ldb_delete(struct ldb_context
*ldb
, const char *dn
);
199 return extended error information from the last call
201 const char *ldb_errstring(struct ldb_context
*ldb
);
204 casefold a string (should be UTF8, but at the moment it isn't)
206 char *ldb_casefold(void *mem_ctx
, const char *s
);
209 ldif manipulation functions
211 int ldb_ldif_write(struct ldb_context
*ldb
,
212 int (*fprintf_fn
)(void *, const char *, ...),
214 const struct ldb_ldif
*ldif
);
215 void ldb_ldif_read_free(struct ldb_context
*ldb
, struct ldb_ldif
*);
216 struct ldb_ldif
*ldb_ldif_read(struct ldb_context
*ldb
,
217 int (*fgetc_fn
)(void *), void *private_data
);
218 struct ldb_ldif
*ldb_ldif_read_file(struct ldb_context
*ldb
, FILE *f
);
219 struct ldb_ldif
*ldb_ldif_read_string(struct ldb_context
*ldb
, const char *s
);
220 int ldb_ldif_write_file(struct ldb_context
*ldb
, FILE *f
, const struct ldb_ldif
*msg
);
223 /* useful functions for ldb_message structure manipulation */
225 int ldb_dn_cmp(const char *dn1
, const char *dn2
);
226 int ldb_attr_cmp(const char *dn1
, const char *dn2
);
229 char *ldb_dn_fold(struct ldb_module
*module
, const char *dn
, int (*case_fold_attr_fn
)(struct ldb_module
* module
, char * attr
));
231 /* create an empty message */
232 struct ldb_message
*ldb_msg_new(void *mem_ctx
);
234 /* find an element within an message */
235 struct ldb_message_element
*ldb_msg_find_element(const struct ldb_message
*msg
,
236 const char *attr_name
);
238 /* compare two ldb_val values - return 0 on match */
239 int ldb_val_equal_exact(const struct ldb_val
*v1
, const struct ldb_val
*v2
);
241 /* find a value within an ldb_message_element */
242 struct ldb_val
*ldb_msg_find_val(const struct ldb_message_element
*el
,
243 struct ldb_val
*val
);
245 /* add a new empty element to a ldb_message */
246 int ldb_msg_add_empty(struct ldb_context
*ldb
,
247 struct ldb_message
*msg
, const char *attr_name
, int flags
);
249 /* add a element to a ldb_message */
250 int ldb_msg_add(struct ldb_context
*ldb
,
251 struct ldb_message
*msg
,
252 const struct ldb_message_element
*el
,
254 int ldb_msg_add_value(struct ldb_context
*ldb
,
255 struct ldb_message
*msg
,
256 const char *attr_name
,
257 const struct ldb_val
*val
);
258 int ldb_msg_add_string(struct ldb_context
*ldb
, struct ldb_message
*msg
,
259 const char *attr_name
, const char *str
);
260 int ldb_msg_add_fmt(struct ldb_context
*ldb
, struct ldb_message
*msg
,
261 const char *attr_name
, const char *fmt
, ...) PRINTF_ATTRIBUTE(4,5);
263 /* compare two message elements - return 0 on match */
264 int ldb_msg_element_compare(struct ldb_message_element
*el1
,
265 struct ldb_message_element
*el2
);
267 /* find elements in a message and convert to a specific type, with
268 a give default value if not found. Assumes that elements are
270 const struct ldb_val
*ldb_msg_find_ldb_val(const struct ldb_message
*msg
, const char *attr_name
);
271 int ldb_msg_find_int(const struct ldb_message
*msg
,
272 const char *attr_name
,
274 unsigned int ldb_msg_find_uint(const struct ldb_message
*msg
,
275 const char *attr_name
,
276 unsigned int default_value
);
277 int64_t ldb_msg_find_int64(const struct ldb_message
*msg
,
278 const char *attr_name
,
279 int64_t default_value
);
280 uint64_t ldb_msg_find_uint64(const struct ldb_message
*msg
,
281 const char *attr_name
,
282 uint64_t default_value
);
283 double ldb_msg_find_double(const struct ldb_message
*msg
,
284 const char *attr_name
,
285 double default_value
);
286 const char *ldb_msg_find_string(const struct ldb_message
*msg
,
287 const char *attr_name
,
288 const char *default_value
);
290 void ldb_msg_sort_elements(struct ldb_message
*msg
);
292 void ldb_msg_free(struct ldb_context
*ldb
, struct ldb_message
*msg
);
294 struct ldb_message
*ldb_msg_copy(struct ldb_context
*ldb
,
295 const struct ldb_message
*msg
);
297 struct ldb_message
*ldb_msg_canonicalize(struct ldb_context
*ldb
,
298 const struct ldb_message
*msg
);
301 struct ldb_message
*ldb_msg_diff(struct ldb_context
*ldb
,
302 struct ldb_message
*msg1
,
303 struct ldb_message
*msg2
);
305 struct ldb_val
ldb_val_dup(void *mem_ctx
, const struct ldb_val
*v
);
308 this allows the user to set a debug function for error reporting
310 int ldb_set_debug(struct ldb_context
*ldb
,
311 void (*debug
)(void *context
, enum ldb_debug_level level
,
312 const char *fmt
, va_list ap
),
315 /* this sets up debug to print messages on stderr */
316 int ldb_set_debug_stderr(struct ldb_context
*ldb
);