4 Copyright (C) Andrew Tridgell 2004
5 Copyright (C) Simo Sorce 2005-2006
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 core API
31 * Description: core API routines interfacing to ldb backends
33 * Author: Andrew Tridgell
37 #include "ldb/include/includes.h"
40 initialise a ldb context
41 The mem_ctx is optional
43 struct ldb_context *ldb_init(void *mem_ctx)
45 struct ldb_context *ldb = talloc_zero(mem_ctx, struct ldb_context);
48 ret = ldb_setup_wellknown_attributes(ldb);
54 ldb_set_utf8_default(ldb);
59 static struct ldb_backend {
61 ldb_connect_fn connect_fn;
62 struct ldb_backend *prev, *next;
63 } *ldb_backends = NULL;
65 register a new ldb backend
67 int ldb_register_backend(const char *url_prefix, ldb_connect_fn connectfn)
69 struct ldb_backend *backend = talloc(talloc_autofree_context(), struct ldb_backend);
71 /* Maybe check for duplicity here later on? */
73 backend->name = talloc_strdup(backend, url_prefix);
74 backend->connect_fn = connectfn;
75 DLIST_ADD(ldb_backends, backend);
80 static ldb_connect_fn ldb_find_backend(const char *url)
82 struct ldb_backend *backend;
84 for (backend = ldb_backends; backend; backend = backend->next) {
85 if (strncmp(backend->name, url, strlen(backend->name)) == 0) {
86 return backend->connect_fn;
94 connect to a database. The URL can either be one of the following forms
98 flags is made up of LDB_FLG_*
100 the options are passed uninterpreted to the backend, and are
103 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[])
109 if (strchr(url, ':') != NULL) {
110 backend = talloc_strndup(ldb, url, strchr(url, ':')-url);
113 backend = talloc_strdup(ldb, "tdb");
116 fn = ldb_find_backend(backend);
119 if (ldb_try_load_dso(ldb, backend) == 0) {
120 fn = ldb_find_backend(backend);
124 talloc_free(backend);
127 ldb_debug(ldb, LDB_DEBUG_FATAL, "Unable to find backend for '%s'\n", url);
128 return LDB_ERR_OTHER;
131 ret = fn(ldb, url, flags, options);
133 if (ret != LDB_SUCCESS) {
134 ldb_debug(ldb, LDB_DEBUG_ERROR, "Failed to connect to '%s'\n", url);
138 if (ldb_load_modules(ldb, options) != LDB_SUCCESS) {
139 ldb_debug(ldb, LDB_DEBUG_FATAL, "Unable to load modules for '%s'\n", url);
140 return LDB_ERR_OTHER;
143 /* TODO: get timeout from options if available there */
144 ldb->default_timeout = 300; /* set default to 5 minutes */
149 void ldb_set_errstring(struct ldb_context *ldb, char *err_string)
151 if (ldb->err_string) {
152 talloc_free(ldb->err_string);
154 ldb->err_string = talloc_steal(ldb, err_string);
157 void ldb_reset_err_string(struct ldb_context *ldb)
159 if (ldb->err_string) {
160 talloc_free(ldb->err_string);
161 ldb->err_string = NULL;
165 #define FIRST_OP(ldb, op) do { \
166 module = ldb->modules; \
167 while (module && module->ops->op == NULL) module = module->next; \
168 if (module == NULL) return LDB_ERR_OPERATIONS_ERROR; \
174 int ldb_transaction_start(struct ldb_context *ldb)
176 struct ldb_module *module;
178 FIRST_OP(ldb, start_transaction);
180 ldb->transaction_active++;
182 ldb_reset_err_string(ldb);
184 status = module->ops->start_transaction(module);
185 if (status != LDB_SUCCESS) {
186 if (ldb->err_string == NULL) {
187 /* no error string was setup by the backend */
188 ldb_set_errstring(ldb,
189 talloc_asprintf(ldb, "ldb transaction start error %d", status));
198 int ldb_transaction_commit(struct ldb_context *ldb)
200 struct ldb_module *module;
202 FIRST_OP(ldb, end_transaction);
204 if (ldb->transaction_active > 0) {
205 ldb->transaction_active--;
207 return LDB_ERR_OPERATIONS_ERROR;
210 ldb_reset_err_string(ldb);
212 status = module->ops->end_transaction(module);
213 if (status != LDB_SUCCESS) {
214 if (ldb->err_string == NULL) {
215 /* no error string was setup by the backend */
216 ldb_set_errstring(ldb,
217 talloc_asprintf(ldb, "ldb transaction commit error %d", status));
226 int ldb_transaction_cancel(struct ldb_context *ldb)
228 struct ldb_module *module;
230 FIRST_OP(ldb, del_transaction);
232 if (ldb->transaction_active > 0) {
233 ldb->transaction_active--;
235 return LDB_ERR_OPERATIONS_ERROR;
238 status = module->ops->del_transaction(module);
239 if (status != LDB_SUCCESS) {
240 if (ldb->err_string == NULL) {
241 /* no error string was setup by the backend */
242 ldb_set_errstring(ldb,
243 talloc_asprintf(ldb, "ldb transaction cancel error %d", status));
249 int ldb_async_wait(struct ldb_async_handle *handle, enum ldb_async_wait_type type)
255 return handle->module->ops->async_wait(handle, type);
258 /* set the specified timeout or, if timeout is 0 set the default timeout */
259 /* timeout == -1 means no timeout */
260 int ldb_set_timeout(struct ldb_context *ldb, struct ldb_request *req, int timeout)
262 if (req == NULL) return LDB_ERR_OPERATIONS_ERROR;
265 req->async.timeout = timeout;
267 req->async.timeout = ldb->default_timeout;
269 req->async.starttime = time(NULL);
274 /* calculates the new timeout based on the previous starttime and timeout */
275 int ldb_set_timeout_from_prev_req(struct ldb_context *ldb, struct ldb_request *oldreq, struct ldb_request *newreq)
279 if (newreq == NULL) return LDB_ERR_OPERATIONS_ERROR;
284 return ldb_set_timeout(ldb, newreq, 0);
286 if ((now - oldreq->async.starttime) > oldreq->async.timeout) {
287 return LDB_ERR_TIME_LIMIT_EXCEEDED;
289 newreq->async.starttime = oldreq->async.starttime;
290 newreq->async.timeout = oldreq->async.timeout - (now - oldreq->async.starttime);
297 NOTE: the request must be a talloc context.
298 returns LDB_ERR_* on errors.
300 int ldb_request(struct ldb_context *ldb, struct ldb_request *req)
302 struct ldb_module *module;
305 ldb_reset_err_string(ldb);
307 /* call the first module in the chain */
308 switch (req->operation) {
310 FIRST_OP(ldb, search);
311 ret = module->ops->search(module, req);
315 ret = module->ops->add(module, req);
318 FIRST_OP(ldb, modify);
319 ret = module->ops->modify(module, req);
323 ret = module->ops->del(module, req);
326 FIRST_OP(ldb, rename);
327 ret = module->ops->rename(module, req);
330 FIRST_OP(ldb, request);
331 ret = module->ops->request(module, req);
339 search the database given a LDAP-like search expression
341 returns an LDB error code
343 Use talloc_free to free the ldb_message returned in 'res', if successful
346 static int ldb_search_callback(struct ldb_context *ldb, void *context, struct ldb_async_result *ares)
348 struct ldb_result *res;
352 ldb_set_errstring(ldb, talloc_asprintf(ldb, "NULL Context in callback"));
353 return LDB_ERR_OPERATIONS_ERROR;
356 res = *((struct ldb_result **)context);
362 if (ares->type == LDB_REPLY_ENTRY) {
363 res->msgs = talloc_realloc(res, res->msgs, struct ldb_message *, res->count + 2);
368 res->msgs[res->count + 1] = NULL;
370 res->msgs[res->count] = talloc_steal(res->msgs, ares->message);
371 if (! res->msgs[res->count]) {
378 if (ares->type == LDB_REPLY_REFERRAL) {
380 for (n = 0; res->refs[n]; n++) /*noop*/ ;
385 res->refs = talloc_realloc(res, res->refs, char *, n + 2);
390 res->refs[n] = talloc_steal(res->refs, ares->referral);
391 res->refs[n + 1] = NULL;
394 if (ares->controls) {
395 res->controls = talloc_steal(res, ares->controls);
396 if (! res->controls) {
407 *((struct ldb_result **)context) = NULL;
408 return LDB_ERR_OPERATIONS_ERROR;
411 int ldb_search(struct ldb_context *ldb,
412 const struct ldb_dn *base,
413 enum ldb_scope scope,
414 const char *expression,
415 const char * const *attrs,
416 struct ldb_result **res)
418 struct ldb_request *req;
421 *res = talloc_zero(ldb, struct ldb_result);
423 return LDB_ERR_OPERATIONS_ERROR;
426 req = talloc(ldb, struct ldb_request);
428 ldb_set_errstring(ldb, talloc_strdup(ldb, "Out of memory!"));
429 return LDB_ERR_OPERATIONS_ERROR;
432 req->operation = LDB_SEARCH;
433 req->op.search.base = base;
434 req->op.search.scope = scope;
436 req->op.search.tree = ldb_parse_tree(req, expression);
437 if (req->op.search.tree == NULL) {
438 ldb_set_errstring(ldb, talloc_strdup(ldb, "Unable to parse search expression"));
440 return LDB_ERR_OPERATIONS_ERROR;
443 req->op.search.attrs = attrs;
444 req->controls = NULL;
445 req->async.context = res;
446 req->async.callback = ldb_search_callback;
447 ldb_set_timeout(ldb, req, 0); /* use default timeout */
449 ret = ldb_request(ldb, req);
451 if (ret == LDB_SUCCESS) {
452 ret = ldb_async_wait(req->async.handle, LDB_WAIT_ALL);
455 if (ret != LDB_SUCCESS) {
464 /* autostarts a transacion if none active */
465 static int ldb_autotransaction_request(struct ldb_context *ldb, struct ldb_request *req)
467 int ret, close_transaction;
469 close_transaction = 0;
470 if (!ldb->transaction_active) {
471 ret = ldb_transaction_start(ldb);
472 if (ret != LDB_SUCCESS) {
475 close_transaction = 1;
478 ret = ldb_request(ldb, req);
479 if (ret == LDB_SUCCESS) {
480 ret = ldb_async_wait(req->async.handle, LDB_WAIT_ALL);
483 if (close_transaction) {
484 if (ret == LDB_SUCCESS) {
485 return ldb_transaction_commit(ldb);
487 ldb_transaction_cancel(ldb);
490 if (ldb->err_string == NULL) {
491 /* no error string was setup by the backend */
492 ldb_set_errstring(ldb,
493 talloc_asprintf(ldb, "%s (%d)",
494 ldb_strerror(ret), ret));
502 add a record to the database. Will fail if a record with the given class and key
505 int ldb_add(struct ldb_context *ldb,
506 const struct ldb_message *message)
508 struct ldb_request *req;
511 ret = ldb_msg_sanity_check(message);
512 if (ret != LDB_SUCCESS) return ret;
514 req = talloc(ldb, struct ldb_request);
516 ldb_set_errstring(ldb, talloc_strdup(ldb, "Out of memory!"));
517 return LDB_ERR_OPERATIONS_ERROR;
520 req->operation = LDB_ADD;
521 req->op.add.message = message;
522 req->controls = NULL;
523 req->async.context = NULL;
524 req->async.callback = NULL;
525 ldb_set_timeout(ldb, req, 0); /* use default timeout */
527 /* do request and autostart a transaction */
528 ret = ldb_autotransaction_request(ldb, req);
535 modify the specified attributes of a record
537 int ldb_modify(struct ldb_context *ldb,
538 const struct ldb_message *message)
540 struct ldb_request *req;
543 ret = ldb_msg_sanity_check(message);
544 if (ret != LDB_SUCCESS) return ret;
546 req = talloc(ldb, struct ldb_request);
548 ldb_set_errstring(ldb, talloc_strdup(ldb, "Out of memory!"));
549 return LDB_ERR_OPERATIONS_ERROR;
552 req->operation = LDB_MODIFY;
553 req->op.add.message = message;
554 req->controls = NULL;
555 req->async.context = NULL;
556 req->async.callback = NULL;
557 ldb_set_timeout(ldb, req, 0); /* use default timeout */
559 /* do request and autostart a transaction */
560 ret = ldb_autotransaction_request(ldb, req);
568 delete a record from the database
570 int ldb_delete(struct ldb_context *ldb, const struct ldb_dn *dn)
572 struct ldb_request *req;
575 req = talloc(ldb, struct ldb_request);
577 ldb_set_errstring(ldb, talloc_strdup(ldb, "Out of memory!"));
578 return LDB_ERR_OPERATIONS_ERROR;
581 req->operation = LDB_DELETE;
583 req->controls = NULL;
584 req->async.context = NULL;
585 req->async.callback = NULL;
586 ldb_set_timeout(ldb, req, 0); /* use default timeout */
588 /* do request and autostart a transaction */
589 ret = ldb_autotransaction_request(ldb, req);
596 rename a record in the database
598 int ldb_rename(struct ldb_context *ldb, const struct ldb_dn *olddn, const struct ldb_dn *newdn)
600 struct ldb_request *req;
603 req = talloc(ldb, struct ldb_request);
605 ldb_set_errstring(ldb, talloc_strdup(ldb, "Out of memory!"));
606 return LDB_ERR_OPERATIONS_ERROR;
609 req->operation = LDB_RENAME;
610 req->op.rename.olddn = olddn;
611 req->op.rename.newdn = newdn;
612 req->controls = NULL;
613 req->async.context = NULL;
614 req->async.callback = NULL;
615 ldb_set_timeout(ldb, req, 0); /* use default timeout */
617 /* do request and autostart a transaction */
618 ret = ldb_autotransaction_request(ldb, req);
627 return extended error information
629 const char *ldb_errstring(struct ldb_context *ldb)
631 if (ldb->err_string) {
632 return ldb->err_string;
639 return a string explaining what a ldb error constant meancs
641 const char *ldb_strerror(int ldb_err)
646 case LDB_ERR_OPERATIONS_ERROR:
647 return "Operations error";
648 case LDB_ERR_PROTOCOL_ERROR:
649 return "Protocol error";
650 case LDB_ERR_TIME_LIMIT_EXCEEDED:
651 return "Time limit exceeded";
652 case LDB_ERR_SIZE_LIMIT_EXCEEDED:
653 return "Size limit exceeded";
654 case LDB_ERR_COMPARE_FALSE:
655 return "Compare false";
656 case LDB_ERR_COMPARE_TRUE:
657 return "Compare true";
658 case LDB_ERR_AUTH_METHOD_NOT_SUPPORTED:
659 return "Auth method not supported";
660 case LDB_ERR_STRONG_AUTH_REQUIRED:
661 return "Strong auth required";
663 case LDB_ERR_REFERRAL:
664 return "Referral error";
665 case LDB_ERR_ADMIN_LIMIT_EXCEEDED:
666 return "Admin limit exceeded";
667 case LDB_ERR_UNSUPPORTED_CRITICAL_EXTENSION:
668 return "Unsupported critical extension";
669 case LDB_ERR_CONFIDENTIALITY_REQUIRED:
670 return "Confidentiality required";
671 case LDB_ERR_SASL_BIND_IN_PROGRESS:
672 return "SASL bind in progress";
673 case LDB_ERR_NO_SUCH_ATTRIBUTE:
674 return "No such attribute";
675 case LDB_ERR_UNDEFINED_ATTRIBUTE_TYPE:
676 return "Undefined attribute type";
677 case LDB_ERR_INAPPROPRIATE_MATCHING:
678 return "Inappropriate matching";
679 case LDB_ERR_CONSTRAINT_VIOLATION:
680 return "Constraint violation";
681 case LDB_ERR_ATTRIBUTE_OR_VALUE_EXISTS:
682 return "Attribute or value exists";
683 case LDB_ERR_INVALID_ATTRIBUTE_SYNTAX:
684 return "Invalid attribute syntax";
686 case LDB_ERR_NO_SUCH_OBJECT:
687 return "No such object";
688 case LDB_ERR_ALIAS_PROBLEM:
689 return "Alias problem";
690 case LDB_ERR_INVALID_DN_SYNTAX:
691 return "Invalid DN syntax";
693 case LDB_ERR_ALIAS_DEREFERENCING_PROBLEM:
694 return "Alias dereferencing problem";
696 case LDB_ERR_INAPPROPRIATE_AUTHENTICATION:
697 return "Inappropriate authentication";
698 case LDB_ERR_INVALID_CREDENTIALS:
699 return "Invalid credentials";
700 case LDB_ERR_INSUFFICIENT_ACCESS_RIGHTS:
701 return "insufficient access rights";
704 case LDB_ERR_UNAVAILABLE:
705 return "Unavailable";
706 case LDB_ERR_UNWILLING_TO_PERFORM:
707 return "Unwilling to perform";
708 case LDB_ERR_LOOP_DETECT:
709 return "Loop detect";
711 case LDB_ERR_NAMING_VIOLATION:
712 return "Naming violation";
713 case LDB_ERR_OBJECT_CLASS_VIOLATION:
714 return "Object class violation";
715 case LDB_ERR_NOT_ALLOWED_ON_NON_LEAF:
716 return "Not allowed on non-leaf";
717 case LDB_ERR_NOT_ALLOWED_ON_RDN:
718 return "Not allowed on RDN";
719 case LDB_ERR_ENTRY_ALREADY_EXISTS:
720 return "Entry already exists";
721 case LDB_ERR_OBJECT_CLASS_MODS_PROHIBITED:
722 return "Object class mods prohibited";
723 /* 70 RESERVED FOR CLDAP */
724 case LDB_ERR_AFFECTS_MULTIPLE_DSAS:
725 return "Affects multiple DSAs";
731 return "Unknown error";
735 set backend specific opaque parameters
737 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value)
739 struct ldb_opaque *o;
741 /* allow updating an existing value */
742 for (o=ldb->opaque;o;o=o->next) {
743 if (strcmp(o->name, name) == 0) {
749 o = talloc(ldb, struct ldb_opaque);
752 return LDB_ERR_OTHER;
754 o->next = ldb->opaque;
762 get a previously set opaque value
764 void *ldb_get_opaque(struct ldb_context *ldb, const char *name)
766 struct ldb_opaque *o;
767 for (o=ldb->opaque;o;o=o->next) {
768 if (strcmp(o->name, name) == 0) {