Reorder arguments to ldb_search() to match what is in Samba 4.
[kai/samba-autobuild/.git] / source3 / lib / ldb / common / ldb.c
1 /* 
2    ldb database library
3
4    Copyright (C) Andrew Tridgell  2004
5    Copyright (C) Simo Sorce  2005-2006
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 3 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, see <http://www.gnu.org/licenses/>.
23 */
24
25 /*
26  *  Name: ldb
27  *
28  *  Component: ldb core API
29  *
30  *  Description: core API routines interfacing to ldb backends
31  *
32  *  Author: Andrew Tridgell
33  */
34
35 #include "includes.h"
36 #include "ldb/include/includes.h"
37
38 /* 
39    initialise a ldb context
40    The mem_ctx is optional
41 */
42 struct ldb_context *ldb_init(void *mem_ctx)
43 {
44         struct ldb_context *ldb = talloc_zero(mem_ctx, struct ldb_context);
45         int ret;
46
47         ret = ldb_setup_wellknown_attributes(ldb);
48         if (ret != 0) {
49                 talloc_free(ldb);
50                 return NULL;
51         }
52
53         ldb_set_utf8_default(ldb);
54         ldb_set_create_perms(ldb, 0600);
55
56         return ldb;
57 }
58
59 static struct ldb_backend {
60         const char *name;
61         ldb_connect_fn connect_fn;
62         struct ldb_backend *prev, *next;
63 } *ldb_backends = NULL;
64
65
66 static ldb_connect_fn ldb_find_backend(const char *url)
67 {
68         struct ldb_backend *backend;
69
70         for (backend = ldb_backends; backend; backend = backend->next) {
71                 if (strncmp(backend->name, url, strlen(backend->name)) == 0) {
72                         return backend->connect_fn;
73                 }
74         }
75
76         return NULL;
77 }
78
79 /*
80  register a new ldb backend
81 */
82 int ldb_register_backend(const char *url_prefix, ldb_connect_fn connectfn)
83 {
84         struct ldb_backend *backend = talloc(talloc_autofree_context(), struct ldb_backend);
85
86         if (ldb_find_backend(url_prefix)) {
87                 return LDB_SUCCESS;
88         }
89
90         /* Maybe check for duplicity here later on? */
91
92         backend->name = talloc_strdup(backend, url_prefix);
93         backend->connect_fn = connectfn;
94         DLIST_ADD(ldb_backends, backend);
95
96         return LDB_SUCCESS;
97 }
98
99 /* 
100    Return the ldb module form of a database. The URL can either be one of the following forms
101    ldb://path
102    ldapi://path
103
104    flags is made up of LDB_FLG_*
105
106    the options are passed uninterpreted to the backend, and are
107    backend specific.
108
109   This allows modules to get at only the backend module, for example where a module 
110   may wish to direct certain requests at a particular backend.
111 */
112 int ldb_connect_backend(struct ldb_context *ldb, const char *url, const char *options[],
113                         struct ldb_module **backend_module)
114 {
115         int ret;
116         char *backend;
117         ldb_connect_fn fn;
118
119         if (strchr(url, ':') != NULL) {
120                 backend = talloc_strndup(ldb, url, strchr(url, ':')-url);
121         } else {
122                 /* Default to tdb */
123                 backend = talloc_strdup(ldb, "tdb");
124         }
125
126         fn = ldb_find_backend(backend);
127
128         if (fn == NULL) {
129                 if (ldb_try_load_dso(ldb, backend) == 0) {
130                         fn = ldb_find_backend(backend);
131                 }
132         }
133
134         talloc_free(backend);
135
136         if (fn == NULL) {
137                 ldb_debug(ldb, LDB_DEBUG_FATAL, "Unable to find backend for '%s'\n", url);
138                 return LDB_ERR_OTHER;
139         }
140
141         ret = fn(ldb, url, ldb->flags, options, backend_module);
142
143         if (ret != LDB_SUCCESS) {
144                 ldb_debug(ldb, LDB_DEBUG_ERROR, "Failed to connect to '%s'\n", url);
145                 return ret;
146         }
147         return ret;
148 }
149
150 /*
151   try to autodetect a basedn if none specified. This fixes one of my
152   pet hates about ldapsearch, which is that you have to get a long,
153   complex basedn right to make any use of it.
154 */
155 static const struct ldb_dn *ldb_set_default_basedn(struct ldb_context *ldb)
156 {
157         TALLOC_CTX *tmp_ctx;
158         int ret;
159         static const char *attrs[] = { "defaultNamingContext", NULL };
160         struct ldb_result *res;
161         struct ldb_dn *basedn=NULL;
162
163         basedn = (struct ldb_dn *)ldb_get_opaque(ldb, "default_baseDN");
164         if (basedn) {
165                 return basedn;
166         }
167
168         tmp_ctx = talloc_new(ldb);
169         ret = ldb_search(ldb, ldb, &res, ldb_dn_new(tmp_ctx), LDB_SCOPE_BASE, 
170                          attrs, "(objectClass=*)");
171         if (ret == LDB_SUCCESS) {
172                 if (res->count == 1) {
173                         basedn = ldb_msg_find_attr_as_dn(ldb, res->msgs[0], "defaultNamingContext");
174                         ldb_set_opaque(ldb, "default_baseDN", basedn);
175                 }
176                 talloc_free(res);
177         }
178
179         talloc_free(tmp_ctx);
180         return basedn;
181 }
182
183 const struct ldb_dn *ldb_get_default_basedn(struct ldb_context *ldb)
184 {
185         return (const struct ldb_dn *)ldb_get_opaque(ldb, "default_baseDN");
186 }
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 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[])
199 {
200         int ret;
201
202         ldb->flags = flags;
203
204         ret = ldb_connect_backend(ldb, url, options, &ldb->modules);
205         if (ret != LDB_SUCCESS) {
206                 return ret;
207         }
208
209         if (ldb_load_modules(ldb, options) != LDB_SUCCESS) {
210                 ldb_debug(ldb, LDB_DEBUG_FATAL, "Unable to load modules for %s: %s\n",
211                           url, ldb_errstring(ldb));
212                 return LDB_ERR_OTHER;
213         }
214
215         /* TODO: get timeout from options if available there */
216         ldb->default_timeout = 300; /* set default to 5 minutes */
217
218         /* set the default base dn */
219         ldb_set_default_basedn(ldb);
220
221         return LDB_SUCCESS;
222 }
223
224 void ldb_set_errstring(struct ldb_context *ldb, const char *err_string)
225 {
226         if (ldb->err_string) {
227                 talloc_free(ldb->err_string);
228         }
229         ldb->err_string = talloc_strdup(ldb, err_string);
230 }
231
232 void ldb_asprintf_errstring(struct ldb_context *ldb, const char *format, ...)
233 {
234         va_list ap;
235
236         if (ldb->err_string) {
237                 talloc_free(ldb->err_string);
238         }
239
240         va_start(ap, format);
241         ldb->err_string = talloc_vasprintf(ldb, format, ap);
242         va_end(ap);
243 }
244
245 void ldb_reset_err_string(struct ldb_context *ldb)
246 {
247         if (ldb->err_string) {
248                 talloc_free(ldb->err_string);
249                 ldb->err_string = NULL;
250         }
251 }
252
253 #define FIRST_OP(ldb, op) do { \
254         module = ldb->modules;                                  \
255         while (module && module->ops->op == NULL) module = module->next; \
256         if (module == NULL) {                                           \
257                 ldb_asprintf_errstring(ldb, "unable to find module or backend to handle operation: " #op); \
258                 return LDB_ERR_OPERATIONS_ERROR;                        \
259         } \
260 } while (0)
261
262 /*
263   start a transaction
264 */
265 static int ldb_transaction_start_internal(struct ldb_context *ldb)
266 {
267         struct ldb_module *module;
268         int status;
269         FIRST_OP(ldb, start_transaction);
270
271         ldb_reset_err_string(ldb);
272
273         status = module->ops->start_transaction(module);
274         if (status != LDB_SUCCESS) {
275                 if (ldb->err_string == NULL) {
276                         /* no error string was setup by the backend */
277                         ldb_asprintf_errstring(ldb,
278                                                 "ldb transaction start: %s (%d)", 
279                                                 ldb_strerror(status), 
280                                                 status);
281                 }
282         }
283         return status;
284 }
285
286 /*
287   commit a transaction
288 */
289 static int ldb_transaction_commit_internal(struct ldb_context *ldb)
290 {
291         struct ldb_module *module;
292         int status;
293         FIRST_OP(ldb, end_transaction);
294
295         ldb_reset_err_string(ldb);
296
297         status = module->ops->end_transaction(module);
298         if (status != LDB_SUCCESS) {
299                 if (ldb->err_string == NULL) {
300                         /* no error string was setup by the backend */
301                         ldb_asprintf_errstring(ldb, 
302                                                 "ldb transaction commit: %s (%d)", 
303                                                 ldb_strerror(status), 
304                                                 status);
305                 }
306         }
307         return status;
308 }
309
310 /*
311   cancel a transaction
312 */
313 static int ldb_transaction_cancel_internal(struct ldb_context *ldb)
314 {
315         struct ldb_module *module;
316         int status;
317         FIRST_OP(ldb, del_transaction);
318
319         status = module->ops->del_transaction(module);
320         if (status != LDB_SUCCESS) {
321                 if (ldb->err_string == NULL) {
322                         /* no error string was setup by the backend */
323                         ldb_asprintf_errstring(ldb, 
324                                                 "ldb transaction cancel: %s (%d)", 
325                                                 ldb_strerror(status), 
326                                                 status);
327                 }
328         }
329         return status;
330 }
331
332 int ldb_transaction_start(struct ldb_context *ldb)
333 {
334         /* disable autotransactions */
335         ldb->transaction_active++;
336
337         return ldb_transaction_start_internal(ldb);
338 }
339
340 int ldb_transaction_commit(struct ldb_context *ldb)
341 {
342         /* renable autotransactions (when we reach 0) */
343         if (ldb->transaction_active > 0)
344                 ldb->transaction_active--;
345
346         return ldb_transaction_commit_internal(ldb);
347 }
348
349 int ldb_transaction_cancel(struct ldb_context *ldb)
350 {
351         /* renable autotransactions (when we reach 0) */
352         if (ldb->transaction_active > 0)
353                 ldb->transaction_active--;
354
355         return ldb_transaction_cancel_internal(ldb);
356 }
357
358 static int ldb_autotransaction_start(struct ldb_context *ldb)
359 {
360         /* explicit transaction active, ignore autotransaction request */
361         if (ldb->transaction_active)
362                 return LDB_SUCCESS;
363
364         return ldb_transaction_start_internal(ldb);
365 }
366
367 static int ldb_autotransaction_commit(struct ldb_context *ldb)
368 {
369         /* explicit transaction active, ignore autotransaction request */
370         if (ldb->transaction_active)
371                 return LDB_SUCCESS;
372
373         return ldb_transaction_commit_internal(ldb);
374 }
375
376 static int ldb_autotransaction_cancel(struct ldb_context *ldb)
377 {
378         /* explicit transaction active, ignore autotransaction request */
379         if (ldb->transaction_active)
380                 return LDB_SUCCESS;
381
382         return ldb_transaction_cancel_internal(ldb);
383 }
384
385 /* autostarts a transacion if none active */
386 static int ldb_autotransaction_request(struct ldb_context *ldb, struct ldb_request *req)
387 {
388         int ret;
389
390         ret = ldb_autotransaction_start(ldb);
391         if (ret != LDB_SUCCESS) {
392                 return ret;
393         }
394
395         ret = ldb_request(ldb, req);
396         if (ret == LDB_SUCCESS) {
397                 ret = ldb_wait(req->handle, LDB_WAIT_ALL);
398         }
399
400         if (ret == LDB_SUCCESS) {
401                 return ldb_autotransaction_commit(ldb);
402         }
403         ldb_autotransaction_cancel(ldb);
404
405         if (ldb->err_string == NULL) {
406                 /* no error string was setup by the backend */
407                 ldb_asprintf_errstring(ldb, "%s (%d)", ldb_strerror(ret), ret);
408         }
409
410         return ret;
411 }
412
413 int ldb_wait(struct ldb_handle *handle, enum ldb_wait_type type)
414 {
415         if (!handle) {
416                 return LDB_SUCCESS;
417         }
418
419         return handle->module->ops->wait(handle, type);
420 }
421
422 /* set the specified timeout or, if timeout is 0 set the default timeout */
423 /* timeout == -1 means no timeout */
424 int ldb_set_timeout(struct ldb_context *ldb, struct ldb_request *req, int timeout)
425 {
426         if (req == NULL) return LDB_ERR_OPERATIONS_ERROR;
427         
428         if (timeout != 0) {
429                 req->timeout = timeout;
430         } else {
431                 req->timeout = ldb->default_timeout;
432         }
433         req->starttime = time(NULL);
434
435         return LDB_SUCCESS;
436 }
437
438 /* calculates the new timeout based on the previous starttime and timeout */
439 int ldb_set_timeout_from_prev_req(struct ldb_context *ldb, struct ldb_request *oldreq, struct ldb_request *newreq)
440 {
441         time_t now;
442
443         if (newreq == NULL) return LDB_ERR_OPERATIONS_ERROR;
444
445         now = time(NULL);
446
447         if (oldreq == NULL)
448                 return ldb_set_timeout(ldb, newreq, 0);
449
450         if ((now - oldreq->starttime) > oldreq->timeout) {
451                 return LDB_ERR_TIME_LIMIT_EXCEEDED;
452         }
453         newreq->starttime = oldreq->starttime;
454         newreq->timeout = oldreq->timeout - (now - oldreq->starttime);
455
456         return LDB_SUCCESS;
457 }
458
459
460 /* 
461    set the permissions for new files to be passed to open() in
462    backends that use local files
463  */
464 void ldb_set_create_perms(struct ldb_context *ldb, unsigned int perms)
465 {
466         ldb->create_perms = perms;
467 }
468
469 /*
470   start an ldb request
471   NOTE: the request must be a talloc context.
472   returns LDB_ERR_* on errors.
473 */
474 int ldb_request(struct ldb_context *ldb, struct ldb_request *req)
475 {
476         struct ldb_module *module;
477         int ret;
478
479         ldb_reset_err_string(ldb);
480
481         /* call the first module in the chain */
482         switch (req->operation) {
483         case LDB_SEARCH:
484                 FIRST_OP(ldb, search);
485                 ret = module->ops->search(module, req);
486                 break;
487         case LDB_ADD:
488                 FIRST_OP(ldb, add);
489                 ret = module->ops->add(module, req);
490                 break;
491         case LDB_MODIFY:
492                 FIRST_OP(ldb, modify);
493                 ret = module->ops->modify(module, req);
494                 break;
495         case LDB_DELETE:
496                 FIRST_OP(ldb, del);
497                 ret = module->ops->del(module, req);
498                 break;
499         case LDB_RENAME:
500                 FIRST_OP(ldb, rename);
501                 ret = module->ops->rename(module, req);
502                 break;
503         case LDB_SEQUENCE_NUMBER:
504                 FIRST_OP(ldb, sequence_number);
505                 ret = module->ops->sequence_number(module, req);
506                 break;
507         default:
508                 FIRST_OP(ldb, request);
509                 ret = module->ops->request(module, req);
510                 break;
511         }
512
513         return ret;
514 }
515
516 /*
517   search the database given a LDAP-like search expression
518
519   returns an LDB error code
520
521   Use talloc_free to free the ldb_message returned in 'res', if successful
522
523 */
524 int ldb_search_default_callback(struct ldb_context *ldb, void *context, struct ldb_reply *ares)
525 {
526         struct ldb_result *res;
527         int n;
528         
529         if (!context) {
530                 ldb_set_errstring(ldb, "NULL Context in callback");
531                 return LDB_ERR_OPERATIONS_ERROR;
532         }       
533
534         res = talloc_get_type(context, struct ldb_result);
535
536         if (!res || !ares) {
537                 ldb_set_errstring(ldb, "NULL res or ares in callback");
538                 goto error;
539         }
540
541         switch (ares->type) {
542         case LDB_REPLY_ENTRY:
543                 res->msgs = talloc_realloc(res, res->msgs, struct ldb_message *, res->count + 2);
544                 if (! res->msgs) {
545                         goto error;
546                 }
547
548                 res->msgs[res->count + 1] = NULL;
549
550                 res->msgs[res->count] = talloc_move(res->msgs, &ares->message);
551                 res->count++;
552                 break;
553         case LDB_REPLY_REFERRAL:
554                 if (res->refs) {
555                         for (n = 0; res->refs[n]; n++) /*noop*/ ;
556                 } else {
557                         n = 0;
558                 }
559
560                 res->refs = talloc_realloc(res, res->refs, char *, n + 2);
561                 if (! res->refs) {
562                         goto error;
563                 }
564
565                 res->refs[n] = talloc_move(res->refs, &ares->referral);
566                 res->refs[n + 1] = NULL;
567         case LDB_REPLY_EXTENDED:
568         case LDB_REPLY_DONE:
569                 /* TODO: we should really support controls on entries and referrals too! */
570                 res->controls = talloc_move(res, &ares->controls);
571                 break;          
572         }
573         talloc_free(ares);
574         return LDB_SUCCESS;
575
576 error:
577         talloc_free(ares);
578         return LDB_ERR_OPERATIONS_ERROR;
579 }
580
581 int ldb_build_search_req(struct ldb_request **ret_req,
582                         struct ldb_context *ldb,
583                         void *mem_ctx,
584                         const struct ldb_dn *base,
585                         enum ldb_scope scope,
586                         const char *expression,
587                         const char * const *attrs,
588                         struct ldb_control **controls,
589                         void *context,
590                         ldb_request_callback_t callback)
591 {
592         struct ldb_request *req;
593
594         *ret_req = NULL;
595
596         req = talloc(mem_ctx, struct ldb_request);
597         if (req == NULL) {
598                 ldb_set_errstring(ldb, "Out of Memory");
599                 return LDB_ERR_OPERATIONS_ERROR;
600         }
601
602         req->operation = LDB_SEARCH;
603         if (base == NULL) {
604                 req->op.search.base = ldb_dn_new(req);
605         } else {
606                 req->op.search.base = base;
607         }
608         req->op.search.scope = scope;
609
610         req->op.search.tree = ldb_parse_tree(req, expression);
611         if (req->op.search.tree == NULL) {
612                 ldb_set_errstring(ldb, "Unable to parse search expression");
613                 talloc_free(req);
614                 return LDB_ERR_OPERATIONS_ERROR;
615         }
616
617         req->op.search.attrs = attrs;
618         req->controls = controls;
619         req->context = context;
620         req->callback = callback;
621
622         *ret_req = req;
623         return LDB_SUCCESS;
624 }
625
626 int ldb_build_add_req(struct ldb_request **ret_req,
627                         struct ldb_context *ldb,
628                         void *mem_ctx,
629                         const struct ldb_message *message,
630                         struct ldb_control **controls,
631                         void *context,
632                         ldb_request_callback_t callback)
633 {
634         struct ldb_request *req;
635
636         *ret_req = NULL;
637
638         req = talloc(mem_ctx, struct ldb_request);
639         if (req == NULL) {
640                 ldb_set_errstring(ldb, "Out of Memory");
641                 return LDB_ERR_OPERATIONS_ERROR;
642         }
643
644         req->operation = LDB_ADD;
645         req->op.add.message = message;
646         req->controls = controls;
647         req->context = context;
648         req->callback = callback;
649
650         *ret_req = req;
651
652         return LDB_SUCCESS;
653 }
654
655 int ldb_build_mod_req(struct ldb_request **ret_req,
656                         struct ldb_context *ldb,
657                         void *mem_ctx,
658                         const struct ldb_message *message,
659                         struct ldb_control **controls,
660                         void *context,
661                         ldb_request_callback_t callback)
662 {
663         struct ldb_request *req;
664
665         *ret_req = NULL;
666
667         req = talloc(mem_ctx, struct ldb_request);
668         if (req == NULL) {
669                 ldb_set_errstring(ldb, "Out of Memory");
670                 return LDB_ERR_OPERATIONS_ERROR;
671         }
672
673         req->operation = LDB_MODIFY;
674         req->op.mod.message = message;
675         req->controls = controls;
676         req->context = context;
677         req->callback = callback;
678
679         *ret_req = req;
680
681         return LDB_SUCCESS;
682 }
683
684 int ldb_build_del_req(struct ldb_request **ret_req,
685                         struct ldb_context *ldb,
686                         void *mem_ctx,
687                         const struct ldb_dn *dn,
688                         struct ldb_control **controls,
689                         void *context,
690                         ldb_request_callback_t callback)
691 {
692         struct ldb_request *req;
693
694         *ret_req = NULL;
695
696         req = talloc(mem_ctx, struct ldb_request);
697         if (req == NULL) {
698                 ldb_set_errstring(ldb, "Out of Memory");
699                 return LDB_ERR_OPERATIONS_ERROR;
700         }
701
702         req->operation = LDB_DELETE;
703         req->op.del.dn = dn;
704         req->controls = controls;
705         req->context = context;
706         req->callback = callback;
707
708         *ret_req = req;
709
710         return LDB_SUCCESS;
711 }
712
713 int ldb_build_rename_req(struct ldb_request **ret_req,
714                         struct ldb_context *ldb,
715                         void *mem_ctx,
716                         const struct ldb_dn *olddn,
717                         const struct ldb_dn *newdn,
718                         struct ldb_control **controls,
719                         void *context,
720                         ldb_request_callback_t callback)
721 {
722         struct ldb_request *req;
723
724         *ret_req = NULL;
725
726         req = talloc(mem_ctx, struct ldb_request);
727         if (req == NULL) {
728                 ldb_set_errstring(ldb, "Out of Memory");
729                 return LDB_ERR_OPERATIONS_ERROR;
730         }
731
732         req->operation = LDB_RENAME;
733         req->op.rename.olddn = olddn;
734         req->op.rename.newdn = newdn;
735         req->controls = controls;
736         req->context = context;
737         req->callback = callback;
738
739         *ret_req = req;
740
741         return LDB_SUCCESS;
742 }
743
744 /*
745   note that ldb_search() will automatically replace a NULL 'base' value with the 
746   defaultNamingContext from the rootDSE if available.
747 */
748 int ldb_search(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
749                            struct ldb_result **_res,
750                            const struct ldb_dn *base,
751                            enum ldb_scope scope,
752                            const char * const *attrs, 
753                            const char *expression)
754 {
755         struct ldb_request *req;
756         int ret;
757         struct ldb_result *res;
758
759         *_res = NULL;
760
761         res = talloc_zero(mem_ctx, struct ldb_result);
762         if (!res) {
763                 return LDB_ERR_OPERATIONS_ERROR;
764         }
765
766         ret = ldb_build_search_req(&req, ldb, mem_ctx,
767                                         base?base:ldb_get_default_basedn(ldb),
768                                         scope,
769                                         expression,
770                                         attrs,
771                                         NULL,
772                                         res,
773                                         ldb_search_default_callback);
774
775         if (ret != LDB_SUCCESS) goto done;
776
777         ldb_set_timeout(ldb, req, 0); /* use default timeout */
778
779         ret = ldb_request(ldb, req);
780         
781         if (ret == LDB_SUCCESS) {
782                 ret = ldb_wait(req->handle, LDB_WAIT_ALL);
783         }
784
785         talloc_free(req);
786
787 done:
788         if (ret != LDB_SUCCESS) {
789                 talloc_free(res);
790                 res = NULL;
791         }
792
793         *_res = res;
794         return ret;
795 }
796
797 /*
798  a useful search function where you can easily define the expression and that
799  takes a memory context where results are allocated
800 */
801
802 int ldb_search_exp_fmt(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, struct ldb_result **result,
803                         struct ldb_dn *base, enum ldb_scope scope, const char * const *attrs,
804                         const char *exp_fmt, ...)
805 {
806         struct ldb_result *res;
807         char *expression;
808         va_list ap;
809         int ret;
810
811         res = NULL;
812         *result = NULL;
813
814         va_start(ap, exp_fmt);
815         expression = talloc_vasprintf(mem_ctx, exp_fmt, ap);
816         va_end(ap);
817
818         if ( ! expression) {
819                 return LDB_ERR_OPERATIONS_ERROR;
820         }
821
822         ret = ldb_search(ldb, ldb, &res, base, scope, attrs, expression);
823
824         if (ret == LDB_SUCCESS) {
825                 talloc_steal(mem_ctx, res);
826                 *result = res;
827         } else {
828                 talloc_free(res);
829         }
830
831         talloc_free(expression);
832
833         return ret;
834 }
835
836 /*
837   add a record to the database. Will fail if a record with the given class and key
838   already exists
839 */
840 int ldb_add(struct ldb_context *ldb, 
841             const struct ldb_message *message)
842 {
843         struct ldb_request *req;
844         int ret;
845
846         ret = ldb_msg_sanity_check(ldb, message);
847         if (ret != LDB_SUCCESS) {
848                 return ret;
849         }
850
851         ret = ldb_build_add_req(&req, ldb, ldb,
852                                         message,
853                                         NULL,
854                                         NULL,
855                                         NULL);
856
857         if (ret != LDB_SUCCESS) return ret;
858
859         ldb_set_timeout(ldb, req, 0); /* use default timeout */
860
861         /* do request and autostart a transaction */
862         ret = ldb_autotransaction_request(ldb, req);
863
864         talloc_free(req);
865         return ret;
866 }
867
868 /*
869   modify the specified attributes of a record
870 */
871 int ldb_modify(struct ldb_context *ldb, 
872                const struct ldb_message *message)
873 {
874         struct ldb_request *req;
875         int ret;
876
877         ret = ldb_msg_sanity_check(ldb, message);
878         if (ret != LDB_SUCCESS) {
879                 return ret;
880         }
881
882         ret = ldb_build_mod_req(&req, ldb, ldb,
883                                         message,
884                                         NULL,
885                                         NULL,
886                                         NULL);
887
888         if (ret != LDB_SUCCESS) return ret;
889
890         ldb_set_timeout(ldb, req, 0); /* use default timeout */
891
892         /* do request and autostart a transaction */
893         ret = ldb_autotransaction_request(ldb, req);
894
895         talloc_free(req);
896         return ret;
897 }
898
899
900 /*
901   delete a record from the database
902 */
903 int ldb_delete(struct ldb_context *ldb, const struct ldb_dn *dn)
904 {
905         struct ldb_request *req;
906         int ret;
907
908         ret = ldb_build_del_req(&req, ldb, ldb,
909                                         dn,
910                                         NULL,
911                                         NULL,
912                                         NULL);
913
914         if (ret != LDB_SUCCESS) return ret;
915
916         ldb_set_timeout(ldb, req, 0); /* use default timeout */
917
918         /* do request and autostart a transaction */
919         ret = ldb_autotransaction_request(ldb, req);
920
921         talloc_free(req);
922         return ret;
923 }
924
925 /*
926   rename a record in the database
927 */
928 int ldb_rename(struct ldb_context *ldb, const struct ldb_dn *olddn, const struct ldb_dn *newdn)
929 {
930         struct ldb_request *req;
931         int ret;
932
933         ret = ldb_build_rename_req(&req, ldb, ldb,
934                                         olddn,
935                                         newdn,
936                                         NULL,
937                                         NULL,
938                                         NULL);
939
940         if (ret != LDB_SUCCESS) return ret;
941
942         ldb_set_timeout(ldb, req, 0); /* use default timeout */
943
944         /* do request and autostart a transaction */
945         ret = ldb_autotransaction_request(ldb, req);
946
947         talloc_free(req);
948         return ret;
949 }
950
951
952 /*
953   return the global sequence number
954 */
955 int ldb_sequence_number(struct ldb_context *ldb, enum ldb_sequence_type type, uint64_t *seq_num)
956 {
957         struct ldb_request *req;
958         int ret;
959
960         req = talloc(ldb, struct ldb_request);
961         if (req == NULL) {
962                 ldb_set_errstring(ldb, "Out of Memory");
963                 return LDB_ERR_OPERATIONS_ERROR;
964         }
965
966         req->operation = LDB_SEQUENCE_NUMBER;
967         req->controls = NULL;
968         req->context = NULL;
969         req->callback = NULL;
970         ldb_set_timeout(ldb, req, 0); /* use default timeout */
971
972         req->op.seq_num.type = type;
973         /* do request and autostart a transaction */
974         ret = ldb_request(ldb, req);
975         
976         if (ret == LDB_SUCCESS) {
977                 *seq_num = req->op.seq_num.seq_num;
978         }
979
980         talloc_free(req);
981         return ret;
982 }
983
984
985
986 /*
987   return extended error information 
988 */
989 const char *ldb_errstring(struct ldb_context *ldb)
990 {
991         if (ldb->err_string) {
992                 return ldb->err_string;
993         }
994
995         return NULL;
996 }
997
998 /*
999   return a string explaining what a ldb error constant meancs
1000 */
1001 const char *ldb_strerror(int ldb_err)
1002 {
1003         switch (ldb_err) {
1004         case LDB_SUCCESS:
1005                 return "Success";
1006         case LDB_ERR_OPERATIONS_ERROR:
1007                 return "Operations error";
1008         case LDB_ERR_PROTOCOL_ERROR:
1009                 return "Protocol error";
1010         case LDB_ERR_TIME_LIMIT_EXCEEDED:
1011                 return "Time limit exceeded";
1012         case LDB_ERR_SIZE_LIMIT_EXCEEDED:
1013                 return "Size limit exceeded";
1014         case LDB_ERR_COMPARE_FALSE:
1015                 return "Compare false";
1016         case LDB_ERR_COMPARE_TRUE:
1017                 return "Compare true";
1018         case LDB_ERR_AUTH_METHOD_NOT_SUPPORTED:
1019                 return "Auth method not supported";
1020         case LDB_ERR_STRONG_AUTH_REQUIRED:
1021                 return "Strong auth required";
1022 /* 9 RESERVED */
1023         case LDB_ERR_REFERRAL:
1024                 return "Referral error";
1025         case LDB_ERR_ADMIN_LIMIT_EXCEEDED:
1026                 return "Admin limit exceeded";
1027         case LDB_ERR_UNSUPPORTED_CRITICAL_EXTENSION:
1028                 return "Unsupported critical extension";
1029         case LDB_ERR_CONFIDENTIALITY_REQUIRED:
1030                 return "Confidentiality required";
1031         case LDB_ERR_SASL_BIND_IN_PROGRESS:
1032                 return "SASL bind in progress";
1033         case LDB_ERR_NO_SUCH_ATTRIBUTE:
1034                 return "No such attribute";
1035         case LDB_ERR_UNDEFINED_ATTRIBUTE_TYPE:
1036                 return "Undefined attribute type";
1037         case LDB_ERR_INAPPROPRIATE_MATCHING:
1038                 return "Inappropriate matching";
1039         case LDB_ERR_CONSTRAINT_VIOLATION:
1040                 return "Constraint violation";
1041         case LDB_ERR_ATTRIBUTE_OR_VALUE_EXISTS:
1042                 return "Attribute or value exists";
1043         case LDB_ERR_INVALID_ATTRIBUTE_SYNTAX:
1044                 return "Invalid attribute syntax";
1045 /* 22-31 unused */
1046         case LDB_ERR_NO_SUCH_OBJECT:
1047                 return "No such object";
1048         case LDB_ERR_ALIAS_PROBLEM:
1049                 return "Alias problem";
1050         case LDB_ERR_INVALID_DN_SYNTAX:
1051                 return "Invalid DN syntax";
1052 /* 35 RESERVED */
1053         case LDB_ERR_ALIAS_DEREFERENCING_PROBLEM:
1054                 return "Alias dereferencing problem";
1055 /* 37-47 unused */
1056         case LDB_ERR_INAPPROPRIATE_AUTHENTICATION:
1057                 return "Inappropriate authentication";
1058         case LDB_ERR_INVALID_CREDENTIALS:
1059                 return "Invalid credentials";
1060         case LDB_ERR_INSUFFICIENT_ACCESS_RIGHTS:
1061                 return "insufficient access rights";
1062         case LDB_ERR_BUSY:
1063                 return "Busy";
1064         case LDB_ERR_UNAVAILABLE:
1065                 return "Unavailable";
1066         case LDB_ERR_UNWILLING_TO_PERFORM:
1067                 return "Unwilling to perform";
1068         case LDB_ERR_LOOP_DETECT:
1069                 return "Loop detect";
1070 /* 55-63 unused */
1071         case LDB_ERR_NAMING_VIOLATION:
1072                 return "Naming violation";
1073         case LDB_ERR_OBJECT_CLASS_VIOLATION:
1074                 return "Object class violation";
1075         case LDB_ERR_NOT_ALLOWED_ON_NON_LEAF:
1076                 return "Not allowed on non-leaf";
1077         case LDB_ERR_NOT_ALLOWED_ON_RDN:
1078                 return "Not allowed on RDN";
1079         case LDB_ERR_ENTRY_ALREADY_EXISTS:
1080                 return "Entry already exists";
1081         case LDB_ERR_OBJECT_CLASS_MODS_PROHIBITED:
1082                 return "Object class mods prohibited";
1083 /* 70 RESERVED FOR CLDAP */
1084         case LDB_ERR_AFFECTS_MULTIPLE_DSAS:
1085                 return "Affects multiple DSAs";
1086 /* 72-79 unused */
1087         case LDB_ERR_OTHER:
1088                 return "Other";
1089         }
1090
1091         return "Unknown error";
1092 }
1093
1094 /*
1095   set backend specific opaque parameters
1096 */
1097 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value)
1098 {
1099         struct ldb_opaque *o;
1100
1101         /* allow updating an existing value */
1102         for (o=ldb->opaque;o;o=o->next) {
1103                 if (strcmp(o->name, name) == 0) {
1104                         o->value = value;
1105                         return LDB_SUCCESS;
1106                 }
1107         }
1108
1109         o = talloc(ldb, struct ldb_opaque);
1110         if (o == NULL) {
1111                 ldb_oom(ldb);
1112                 return LDB_ERR_OTHER;
1113         }
1114         o->next = ldb->opaque;
1115         o->name = name;
1116         o->value = value;
1117         ldb->opaque = o;
1118         return LDB_SUCCESS;
1119 }
1120
1121 /*
1122   get a previously set opaque value
1123 */
1124 void *ldb_get_opaque(struct ldb_context *ldb, const char *name)
1125 {
1126         struct ldb_opaque *o;
1127         for (o=ldb->opaque;o;o=o->next) {
1128                 if (strcmp(o->name, name) == 0) {
1129                         return o->value;
1130                 }
1131         }
1132         return NULL;
1133 }