4 Copyright (C) Andrew Tridgell 2004
5 Copyright (C) Stefan Metzmacher 2004
6 Copyright (C) Simo Sorce 2005-2006
8 ** NOTE! The following LGPL license applies to the ldb
9 ** library. This does NOT imply that all of Samba is released
12 This library is free software; you can redistribute it and/or
13 modify it under the terms of the GNU Lesser General Public
14 License as published by the Free Software Foundation; either
15 version 3 of the License, or (at your option) any later version.
17 This library is distributed in the hope that it will be useful,
18 but WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
22 You should have received a copy of the GNU Lesser General Public
23 License along with this library; if not, see <http://www.gnu.org/licenses/>.
29 * Component: ldb header
31 * Description: defines for base ldb API
33 * Author: Andrew Tridgell
34 * Author: Stefan Metzmacher
38 \file ldb.h Samba's ldb database
40 This header file provides the main API for ldb.
45 /*! \cond DOXYGEN_IGNORE */
52 #include "ldb_errors.h"
55 major restrictions as compared to normal LDAP:
57 - each record must have a unique key field
58 - the key must be representable as a NULL terminated C string and may not
59 contain a comma or braces
61 major restrictions as compared to tdb:
63 - no explicit locking calls, but we have transactions when using ldb_tdb
71 An individual lump of data in a result comes in this format. The
72 pointer will usually be to a UTF-8 string if the application is
73 sensible, but it can be to anything you like, including binary data
74 blobs of arbitrary size.
76 \note the data is null (0x00) terminated, but the length does not
77 include the terminator.
80 uint8_t *data; /*!< result data */
81 size_t length; /*!< length of data */
85 /*! \cond DOXYGEN_IGNORE */
86 #ifndef PRINTF_ATTRIBUTE
87 #define PRINTF_ATTRIBUTE(a,b)
91 /* opaque ldb_dn structures, see ldb_dn.c for internals */
92 struct ldb_dn_component;
96 There are a number of flags that are used with ldap_modify() in
97 ldb_message_element.flags fields. The LDB_FLAGS_MOD_ADD,
98 LDB_FLAGS_MOD_DELETE and LDB_FLAGS_MOD_REPLACE flags are used in
99 ldap_modify() calls to specify whether attributes are being added,
100 deleted or modified respectively.
102 #define LDB_FLAG_MOD_MASK 0x3
105 Flag value used in ldap_modify() to indicate that attributes are
108 \sa LDB_FLAG_MOD_MASK
110 #define LDB_FLAG_MOD_ADD 1
113 Flag value used in ldap_modify() to indicate that attributes are
116 \sa LDB_FLAG_MOD_MASK
118 #define LDB_FLAG_MOD_REPLACE 2
121 Flag value used in ldap_modify() to indicate that attributes are
124 \sa LDB_FLAG_MOD_MASK
126 #define LDB_FLAG_MOD_DELETE 3
129 OID for logic AND comaprison.
131 This is the well known object ID for a logical AND comparitor.
133 #define LDB_OID_COMPARATOR_AND "1.2.840.113556.1.4.803"
136 OID for logic OR comparison.
138 This is the well known object ID for a logical OR comparitor.
140 #define LDB_OID_COMPARATOR_OR "1.2.840.113556.1.4.804"
143 results are given back as arrays of ldb_message_element
145 struct ldb_message_element {
148 unsigned int num_values;
149 struct ldb_val *values;
154 a ldb_message represents all or part of a record. It can contain an arbitrary
159 unsigned int num_elements;
160 struct ldb_message_element *elements;
163 enum ldb_changetype {
164 LDB_CHANGETYPE_NONE=0,
166 LDB_CHANGETYPE_DELETE,
167 LDB_CHANGETYPE_MODIFY
173 This structure contains a LDIF record, as returned from ldif_read()
174 and equivalent functions.
177 enum ldb_changetype changetype; /*!< The type of change */
178 struct ldb_message *msg; /*!< The changes */
181 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
183 LDB_SCOPE_ONELEVEL=1,
184 LDB_SCOPE_SUBTREE=2};
187 struct tevent_context;
189 /* debugging uses one of the following levels */
190 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR,
191 LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
194 the user can optionally supply a debug function. The function
195 is based on the vfprintf() style of interface, but with the addition
198 struct ldb_debug_ops {
199 void (*debug)(void *context, enum ldb_debug_level level,
200 const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0);
205 The user can optionally supply a custom utf8 functions,
206 to handle comparisons and casefolding.
208 struct ldb_utf8_fns {
210 char *(*casefold)(void *context, TALLOC_CTX *mem_ctx, const char *s, size_t n);
214 Flag value for database connection mode.
216 If LDB_FLG_RDONLY is used in ldb_connect, then the database will be
217 opened read-only, if possible.
219 #define LDB_FLG_RDONLY 1
222 Flag value for database connection mode.
224 If LDB_FLG_NOSYNC is used in ldb_connect, then the database will be
225 opened without synchronous operations, if possible.
227 #define LDB_FLG_NOSYNC 2
230 Flag value to specify autoreconnect mode.
232 If LDB_FLG_RECONNECT is used in ldb_connect, then the backend will
233 be opened in a way that makes it try to auto reconnect if the
234 connection is dropped (actually make sense only with ldap).
236 #define LDB_FLG_RECONNECT 4
239 Flag to tell backends not to use mmap
241 #define LDB_FLG_NOMMAP 8
244 Flag to tell ldif handlers not to force encoding of binary
247 #define LDB_FLG_SHOW_BINARY 16
250 structures for ldb_parse_tree handling code
252 enum ldb_parse_op { LDB_OP_AND=1, LDB_OP_OR=2, LDB_OP_NOT=3,
253 LDB_OP_EQUALITY=4, LDB_OP_SUBSTRING=5,
254 LDB_OP_GREATER=6, LDB_OP_LESS=7, LDB_OP_PRESENT=8,
255 LDB_OP_APPROX=9, LDB_OP_EXTENDED=10 };
257 struct ldb_parse_tree {
258 enum ldb_parse_op operation;
261 struct ldb_parse_tree *child;
265 struct ldb_val value;
269 int start_with_wildcard;
270 int end_with_wildcard;
271 struct ldb_val **chunks;
278 struct ldb_val value;
284 struct ldb_val value;
287 unsigned int num_elements;
288 struct ldb_parse_tree **elements;
293 struct ldb_parse_tree *ldb_parse_tree(TALLOC_CTX *mem_ctx, const char *s);
294 char *ldb_filter_from_tree(TALLOC_CTX *mem_ctx, struct ldb_parse_tree *tree);
299 This function encodes a binary blob using the encoding rules in RFC
300 2254 (Section 4). This function also escapes any non-printable
303 \param mem_ctx the memory context to allocate the return string in.
304 \param val the (potentially) binary data to be encoded
306 \return the encoded data as a null terminated string
308 \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>.
310 char *ldb_binary_encode(TALLOC_CTX *mem_ctx, struct ldb_val val);
315 This function encodes a string using the encoding rules in RFC 2254
316 (Section 4). This function also escapes any non-printable
319 \param mem_ctx the memory context to allocate the return string in.
320 \param string the string to be encoded
322 \return the encoded data as a null terminated string
324 \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>.
326 char *ldb_binary_encode_string(TALLOC_CTX *mem_ctx, const char *string);
329 functions for controlling attribute handling
331 typedef int (*ldb_attr_handler_t)(struct ldb_context *, TALLOC_CTX *mem_ctx, const struct ldb_val *, struct ldb_val *);
332 typedef int (*ldb_attr_comparison_t)(struct ldb_context *, TALLOC_CTX *mem_ctx, const struct ldb_val *, const struct ldb_val *);
335 attribute handler structure
337 attr -> The attribute name
338 ldif_read_fn -> convert from ldif to binary format
339 ldif_write_fn -> convert from binary to ldif format
340 canonicalise_fn -> canonicalise a value, for use by indexing and dn construction
341 comparison_fn -> compare two values
344 struct ldb_schema_syntax {
346 ldb_attr_handler_t ldif_read_fn;
347 ldb_attr_handler_t ldif_write_fn;
348 ldb_attr_handler_t canonicalise_fn;
349 ldb_attr_comparison_t comparison_fn;
352 struct ldb_schema_attribute {
355 const struct ldb_schema_syntax *syntax;
358 const struct ldb_schema_attribute *ldb_schema_attribute_by_name(struct ldb_context *ldb,
361 struct ldb_dn_extended_syntax {
363 ldb_attr_handler_t read_fn;
364 ldb_attr_handler_t write_clear_fn;
365 ldb_attr_handler_t write_hex_fn;
368 const struct ldb_dn_extended_syntax *ldb_dn_extended_syntax_by_name(struct ldb_context *ldb,
372 The attribute is not returned by default
374 #define LDB_ATTR_FLAG_HIDDEN (1<<0)
376 /* the attribute handler name should be freed when released */
377 #define LDB_ATTR_FLAG_ALLOCATED (1<<1)
380 The attribute is supplied by the application and should not be removed
382 #define LDB_ATTR_FLAG_FIXED (1<<2)
385 when this is set, attempts to create two records which have the same
386 value for this attribute will return LDB_ERR_ENTRY_ALREADY_EXISTS
388 #define LDB_ATTR_FLAG_UNIQUE_INDEX (1<<3)
391 LDAP attribute syntax for a DN
393 This is the well-known LDAP attribute syntax for a DN.
395 See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
397 #define LDB_SYNTAX_DN "1.3.6.1.4.1.1466.115.121.1.12"
400 LDAP attribute syntax for a Directory String
402 This is the well-known LDAP attribute syntax for a Directory String.
404 \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
406 #define LDB_SYNTAX_DIRECTORY_STRING "1.3.6.1.4.1.1466.115.121.1.15"
409 LDAP attribute syntax for an integer
411 This is the well-known LDAP attribute syntax for an integer.
413 See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
415 #define LDB_SYNTAX_INTEGER "1.3.6.1.4.1.1466.115.121.1.27"
418 LDAP attribute syntax for a boolean
420 This is the well-known LDAP attribute syntax for a boolean.
422 See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
424 #define LDB_SYNTAX_BOOLEAN "1.3.6.1.4.1.1466.115.121.1.7"
427 LDAP attribute syntax for an octet string
429 This is the well-known LDAP attribute syntax for an octet string.
431 See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
433 #define LDB_SYNTAX_OCTET_STRING "1.3.6.1.4.1.1466.115.121.1.40"
436 LDAP attribute syntax for UTC time.
438 This is the well-known LDAP attribute syntax for a UTC time.
440 See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
442 #define LDB_SYNTAX_UTC_TIME "1.3.6.1.4.1.1466.115.121.1.53"
444 #define LDB_SYNTAX_OBJECTCLASS "LDB_SYNTAX_OBJECTCLASS"
446 /* sorting helpers */
447 typedef int (*ldb_qsort_cmp_fn_t) (void *v1, void *v2, void *opaque);
450 OID for the paged results control. This control is included in the
451 searchRequest and searchResultDone messages as part of the controls
452 field of the LDAPMessage, as defined in Section 4.1.12 of
455 \sa <a href="http://www.ietf.org/rfc/rfc2696.txt">RFC 2696</a>.
457 #define LDB_CONTROL_PAGED_RESULTS_OID "1.2.840.113556.1.4.319"
460 OID for specifying the returned elements of the ntSecurityDescriptor
462 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_sd_flags_oid.asp">Microsoft documentation of this OID</a>
464 #define LDB_CONTROL_SD_FLAGS_OID "1.2.840.113556.1.4.801"
467 OID for specifying an advanced scope for the search (one partition)
469 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_domain_scope_oid.asp">Microsoft documentation of this OID</a>
471 #define LDB_CONTROL_DOMAIN_SCOPE_OID "1.2.840.113556.1.4.1339"
474 OID for specifying an advanced scope for a search
476 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_search_options_oid.asp">Microsoft documentation of this OID</a>
478 #define LDB_CONTROL_SEARCH_OPTIONS_OID "1.2.840.113556.1.4.1340"
483 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_notification_oid.asp">Microsoft documentation of this OID</a>
485 #define LDB_CONTROL_NOTIFICATION_OID "1.2.840.113556.1.4.528"
488 OID for getting deleted objects
490 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_show_deleted_oid.asp">Microsoft documentation of this OID</a>
492 #define LDB_CONTROL_SHOW_DELETED_OID "1.2.840.113556.1.4.417"
495 OID for getting recycled objects
497 \sa <a href="http://msdn.microsoft.com/en-us/library/dd304621(PROT.13).aspx">Microsoft documentation of this OID</a>
499 #define LDB_CONTROL_SHOW_RECYCLED_OID "1.2.840.113556.1.4.2064"
502 OID for getting deactivated linked attributes
504 \sa <a href="http://msdn.microsoft.com/en-us/library/dd302781(PROT.13).aspx">Microsoft documentation of this OID</a>
506 #define LDB_CONTROL_SHOW_DEACTIVATED_LINK_OID "1.2.840.113556.1.4.2065"
511 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_extended_dn_oid.asp">Microsoft documentation of this OID</a>
513 #define LDB_CONTROL_EXTENDED_DN_OID "1.2.840.113556.1.4.529"
516 OID for LDAP server sort result extension.
518 This control is included in the searchRequest message as part of
519 the controls field of the LDAPMessage, as defined in Section 4.1.12
520 of LDAP v3. The controlType is set to
521 "1.2.840.113556.1.4.473". The criticality MAY be either TRUE or
522 FALSE (where absent is also equivalent to FALSE) at the client's
525 \sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
527 #define LDB_CONTROL_SERVER_SORT_OID "1.2.840.113556.1.4.473"
530 OID for LDAP server sort result response extension.
532 This control is included in the searchResultDone message as part of
533 the controls field of the LDAPMessage, as defined in Section 4.1.12 of
536 \sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
538 #define LDB_CONTROL_SORT_RESP_OID "1.2.840.113556.1.4.474"
541 OID for LDAP Attribute Scoped Query extension.
543 This control is included in SearchRequest or SearchResponse
544 messages as part of the controls field of the LDAPMessage.
546 #define LDB_CONTROL_ASQ_OID "1.2.840.113556.1.4.1504"
549 OID for LDAP Directory Sync extension.
551 This control is included in SearchRequest or SearchResponse
552 messages as part of the controls field of the LDAPMessage.
554 #define LDB_CONTROL_DIRSYNC_OID "1.2.840.113556.1.4.841"
558 OID for LDAP Virtual List View Request extension.
560 This control is included in SearchRequest messages
561 as part of the controls field of the LDAPMessage.
563 #define LDB_CONTROL_VLV_REQ_OID "2.16.840.1.113730.3.4.9"
566 OID for LDAP Virtual List View Response extension.
568 This control is included in SearchResponse messages
569 as part of the controls field of the LDAPMessage.
571 #define LDB_CONTROL_VLV_RESP_OID "2.16.840.1.113730.3.4.10"
574 OID to let modifies don't give an error when adding an existing
575 attribute with the same value or deleting an nonexisting one attribute
577 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_permissive_modify_oid.asp">Microsoft documentation of this OID</a>
579 #define LDB_CONTROL_PERMISSIVE_MODIFY_OID "1.2.840.113556.1.4.1413"
582 OID for LDAP Extended Operation START_TLS.
584 This Extended operation is used to start a new TLS
585 channel on top of a clear text channel.
587 #define LDB_EXTENDED_START_TLS_OID "1.3.6.1.4.1.1466.20037"
591 #define LDB_EXTENDED_DYNAMIC_OID "1.3.6.1.4.1.1466.101.119.1"
595 #define LDB_EXTENDED_FAST_BIND_OID "1.2.840.113556.1.4.1781"
597 struct ldb_sd_flags_control {
599 * request the owner 0x00000001
600 * request the group 0x00000002
601 * request the DACL 0x00000004
602 * request the SACL 0x00000008
604 unsigned secinfo_flags;
608 * DOMAIN_SCOPE 0x00000001
609 * this limits the search to one partition,
610 * and no referrals will be returned.
611 * (Note this doesn't limit the entries by there
612 * objectSid belonging to a domain! Builtin and Foreign Sids
613 * are still returned)
615 * PHANTOM_ROOT 0x00000002
616 * this search on the whole tree on a domain controller
617 * over multiple partitions without referrals.
618 * (This is the default behavior on the Global Catalog Port)
621 #define LDB_SEARCH_OPTION_DOMAIN_SCOPE 0x00000001
622 #define LDB_SEARCH_OPTION_PHANTOM_ROOT 0x00000002
624 struct ldb_search_options_control {
625 unsigned search_options;
628 struct ldb_paged_control {
634 struct ldb_extended_dn_control {
638 struct ldb_server_sort_control {
644 struct ldb_sort_resp_control {
649 struct ldb_asq_control {
651 char *source_attribute;
656 struct ldb_dirsync_control {
663 struct ldb_vlv_req_control {
681 struct ldb_vlv_resp_control {
695 enum ldb_request_type {
702 LDB_REQ_REGISTER_CONTROL,
703 LDB_REQ_REGISTER_PARTITION
706 enum ldb_reply_type {
723 struct ldb_extended {
725 void *data; /* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
728 #define LDB_EXTENDED_SEQUENCE_NUMBER "1.3.6.1.4.1.7165.4.4.3"
730 enum ldb_sequence_type {
732 LDB_SEQ_HIGHEST_TIMESTAMP,
736 #define LDB_SEQ_GLOBAL_SEQUENCE 0x01
737 #define LDB_SEQ_TIMESTAMP_SEQUENCE 0x02
739 struct ldb_seqnum_request {
740 enum ldb_sequence_type type;
743 struct ldb_seqnum_result {
750 struct ldb_message **msgs;
751 struct ldb_extended *extended;
752 struct ldb_control **controls;
758 enum ldb_reply_type type;
759 struct ldb_message *message;
760 struct ldb_extended *response;
761 struct ldb_control **controls;
770 enum ldb_scope scope;
771 struct ldb_parse_tree *tree;
772 const char * const *attrs;
773 struct ldb_result *res;
777 const struct ldb_message *message;
781 const struct ldb_message *message;
789 struct ldb_dn *olddn;
790 struct ldb_dn *newdn;
793 struct ldb_register_control {
797 struct ldb_register_partition {
801 typedef int (*ldb_request_callback_t)(struct ldb_request *, struct ldb_reply *);
805 enum ldb_request_type operation;
808 struct ldb_search search;
810 struct ldb_modify mod;
811 struct ldb_delete del;
812 struct ldb_rename rename;
813 struct ldb_extended extended;
814 struct ldb_register_control reg_control;
815 struct ldb_register_partition reg_partition;
818 struct ldb_control **controls;
821 ldb_request_callback_t callback;
825 struct ldb_handle *handle;
828 int ldb_request(struct ldb_context *ldb, struct ldb_request *request);
829 int ldb_request_done(struct ldb_request *req, int status);
830 bool ldb_request_is_done(struct ldb_request *req);
832 int ldb_modules_wait(struct ldb_handle *handle);
833 int ldb_wait(struct ldb_handle *handle, enum ldb_wait_type type);
835 int ldb_set_timeout(struct ldb_context *ldb, struct ldb_request *req, int timeout);
836 int ldb_set_timeout_from_prev_req(struct ldb_context *ldb, struct ldb_request *oldreq, struct ldb_request *newreq);
837 void ldb_set_create_perms(struct ldb_context *ldb, unsigned int perms);
838 void ldb_set_modules_dir(struct ldb_context *ldb, const char *path);
839 struct tevent_context;
840 void ldb_set_event_context(struct ldb_context *ldb, struct tevent_context *ev);
841 struct tevent_context * ldb_get_event_context(struct ldb_context *ldb);
844 Initialise ldbs' global information
846 This is required before any other LDB call
848 \return 0 if initialisation succeeded, -1 otherwise
850 int ldb_global_init(void);
853 Initialise an ldb context
855 This is required before any other LDB call.
857 \param mem_ctx pointer to a talloc memory context. Pass NULL if there is
858 no suitable context available.
860 \return pointer to ldb_context that should be free'd (using talloc_free())
861 at the end of the program.
863 struct ldb_context *ldb_init(TALLOC_CTX *mem_ctx, struct tevent_context *ev_ctx);
866 Connect to a database.
868 This is typically called soon after ldb_init(), and is required prior to
869 any search or database modification operations.
871 The URL can be one of the following forms:
877 \param ldb the context associated with the database (from ldb_init())
878 \param url the URL of the database to connect to, as noted above
879 \param flags a combination of LDB_FLG_* to modify the connection behaviour
880 \param options backend specific options - passed uninterpreted to the backend
882 \return result code (LDB_SUCCESS on success, or a failure code)
884 \note It is an error to connect to a database that does not exist in readonly mode
885 (that is, with LDB_FLG_RDONLY). However in read-write mode, the database will be
886 created if it does not exist.
889 typedef void (*ldb_async_timeout_fn) (void *);
890 typedef bool (*ldb_async_callback_fn) (void *);
891 typedef int (*ldb_async_ctx_add_op_fn)(void *, time_t, void *, ldb_async_timeout_fn, ldb_async_callback_fn);
892 typedef int (*ldb_async_ctx_wait_op_fn)(void *);
894 void ldb_async_ctx_set_private_data(struct ldb_context *ldb,
896 void ldb_async_ctx_set_add_op(struct ldb_context *ldb,
897 ldb_async_ctx_add_op_fn add_op);
898 void ldb_async_ctx_set_wait_op(struct ldb_context *ldb,
899 ldb_async_ctx_wait_op_fn wait_op);
901 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
904 return an automatic basedn from the rootDomainNamingContext of the rootDSE
905 This value have been set in an opaque pointer at connection time
907 struct ldb_dn *ldb_get_root_basedn(struct ldb_context *ldb);
910 return an automatic basedn from the configurationNamingContext of the rootDSE
911 This value have been set in an opaque pointer at connection time
913 struct ldb_dn *ldb_get_config_basedn(struct ldb_context *ldb);
916 return an automatic basedn from the schemaNamingContext of the rootDSE
917 This value have been set in an opaque pointer at connection time
919 struct ldb_dn *ldb_get_schema_basedn(struct ldb_context *ldb);
922 return an automatic baseDN from the defaultNamingContext of the rootDSE
923 This value have been set in an opaque pointer at connection time
925 struct ldb_dn *ldb_get_default_basedn(struct ldb_context *ldb);
928 The default async search callback function
930 \param req the request we are callback of
931 \param ares a single reply from the async core
933 \return result code (LDB_SUCCESS on success, or a failure code)
935 \note this function expects req->context to always be an struct ldb_result pointer
936 AND a talloc context, this function will steal on the context each message
937 from the ares reply passed on by the async core so that in the end all the
938 messages will be in the context (ldb_result) memory tree.
939 Freeing the passed context (ldb_result tree) will free all the resources
940 (the request need to be freed separately and the result doe not depend on the
941 request that can be freed as sson as the search request is finished)
944 int ldb_search_default_callback(struct ldb_request *req, struct ldb_reply *ares);
947 The default async extended operation callback function
949 \param req the request we are callback of
950 \param ares a single reply from the async core
952 \return result code (LDB_SUCCESS on success, or a failure code)
954 int ldb_op_default_callback(struct ldb_request *req, struct ldb_reply *ares);
958 Helper function to build a search request
960 \param ret_req the request structure is returned here (talloced on mem_ctx)
961 \param ldb the context associated with the database (from ldb_init())
962 \param mem_ctx a talloc memory context (used as parent of ret_req)
963 \param base the Base Distinguished Name for the query (use ldb_dn_new() for an empty one)
964 \param scope the search scope for the query
965 \param expression the search expression to use for this query
966 \param attrs the search attributes for the query (pass NULL if none required)
967 \param controls an array of controls
968 \param context the callback function context
969 \param the callback function to handle the async replies
970 \param the parent request if any
972 \return result code (LDB_SUCCESS on success, or a failure code)
975 int ldb_build_search_req(struct ldb_request **ret_req,
976 struct ldb_context *ldb,
979 enum ldb_scope scope,
980 const char *expression,
981 const char * const *attrs,
982 struct ldb_control **controls,
984 ldb_request_callback_t callback,
985 struct ldb_request *parent);
987 int ldb_build_search_req_ex(struct ldb_request **ret_req,
988 struct ldb_context *ldb,
991 enum ldb_scope scope,
992 struct ldb_parse_tree *tree,
993 const char * const *attrs,
994 struct ldb_control **controls,
996 ldb_request_callback_t callback,
997 struct ldb_request *parent);
1000 Helper function to build an add request
1002 \param ret_req the request structure is returned here (talloced on mem_ctx)
1003 \param ldb the context associated with the database (from ldb_init())
1004 \param mem_ctx a talloc memory context (used as parent of ret_req)
1005 \param message contains the entry to be added
1006 \param controls an array of controls
1007 \param context the callback function context
1008 \param the callback function to handle the async replies
1009 \param the parent request if any
1011 \return result code (LDB_SUCCESS on success, or a failure code)
1014 int ldb_build_add_req(struct ldb_request **ret_req,
1015 struct ldb_context *ldb,
1016 TALLOC_CTX *mem_ctx,
1017 const struct ldb_message *message,
1018 struct ldb_control **controls,
1020 ldb_request_callback_t callback,
1021 struct ldb_request *parent);
1024 Helper function to build a modify request
1026 \param ret_req the request structure is returned here (talloced on mem_ctx)
1027 \param ldb the context associated with the database (from ldb_init())
1028 \param mem_ctx a talloc memory context (used as parent of ret_req)
1029 \param message contains the entry to be modified
1030 \param controls an array of controls
1031 \param context the callback function context
1032 \param the callback function to handle the async replies
1033 \param the parent request if any
1035 \return result code (LDB_SUCCESS on success, or a failure code)
1038 int ldb_build_mod_req(struct ldb_request **ret_req,
1039 struct ldb_context *ldb,
1040 TALLOC_CTX *mem_ctx,
1041 const struct ldb_message *message,
1042 struct ldb_control **controls,
1044 ldb_request_callback_t callback,
1045 struct ldb_request *parent);
1048 Helper function to build a delete request
1050 \param ret_req the request structure is returned here (talloced on mem_ctx)
1051 \param ldb the context associated with the database (from ldb_init())
1052 \param mem_ctx a talloc memory context (used as parent of ret_req)
1053 \param dn the DN to be deleted
1054 \param controls an array of controls
1055 \param context the callback function context
1056 \param the callback function to handle the async replies
1057 \param the parent request if any
1059 \return result code (LDB_SUCCESS on success, or a failure code)
1062 int ldb_build_del_req(struct ldb_request **ret_req,
1063 struct ldb_context *ldb,
1064 TALLOC_CTX *mem_ctx,
1066 struct ldb_control **controls,
1068 ldb_request_callback_t callback,
1069 struct ldb_request *parent);
1072 Helper function to build a rename request
1074 \param ret_req the request structure is returned here (talloced on mem_ctx)
1075 \param ldb the context associated with the database (from ldb_init())
1076 \param mem_ctx a talloc memory context (used as parent of ret_req)
1077 \param olddn the old DN
1078 \param newdn the new DN
1079 \param controls an array of controls
1080 \param context the callback function context
1081 \param the callback function to handle the async replies
1082 \param the parent request if any
1084 \return result code (LDB_SUCCESS on success, or a failure code)
1087 int ldb_build_rename_req(struct ldb_request **ret_req,
1088 struct ldb_context *ldb,
1089 TALLOC_CTX *mem_ctx,
1090 struct ldb_dn *olddn,
1091 struct ldb_dn *newdn,
1092 struct ldb_control **controls,
1094 ldb_request_callback_t callback,
1095 struct ldb_request *parent);
1098 Add a ldb_control to a ldb_request
1100 \param req the request struct where to add the control
1101 \param oid the object identifier of the control as string
1102 \param critical whether the control should be critical or not
1103 \param data a talloc pointer to the control specific data
1105 \return result code (LDB_SUCCESS on success, or a failure code)
1107 int ldb_request_add_control(struct ldb_request *req, const char *oid, bool critical, void *data);
1110 check if a control with the specified "oid" exist and return it
1111 \param req the request struct where to add the control
1112 \param oid the object identifier of the control as string
1114 \return the control, NULL if not found
1116 struct ldb_control *ldb_request_get_control(struct ldb_request *req, const char *oid);
1119 check if a control with the specified "oid" exist and return it
1120 \param rep the reply struct where to add the control
1121 \param oid the object identifier of the control as string
1123 \return the control, NULL if not found
1125 struct ldb_control *ldb_reply_get_control(struct ldb_reply *rep, const char *oid);
1130 This function searches the database, and returns
1131 records that match an LDAP-like search expression
1133 \param ldb the context associated with the database (from ldb_init())
1134 \param mem_ctx the memory context to use for the request and the results
1135 \param result the return result
1136 \param base the Base Distinguished Name for the query (use ldb_dn_new() for an empty one)
1137 \param scope the search scope for the query
1138 \param attrs the search attributes for the query (pass NULL if none required)
1139 \param exp_fmt the search expression to use for this query (printf like)
1141 \return result code (LDB_SUCCESS on success, or a failure code)
1143 \note use talloc_free() to free the ldb_result returned
1145 int ldb_search(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
1146 struct ldb_result **result, struct ldb_dn *base,
1147 enum ldb_scope scope, const char * const *attrs,
1148 const char *exp_fmt, ...) PRINTF_ATTRIBUTE(7,8);
1151 Add a record to the database.
1153 This function adds a record to the database. This function will fail
1154 if a record with the specified class and key already exists in the
1157 \param ldb the context associated with the database (from
1159 \param message the message containing the record to add.
1161 \return result code (LDB_SUCCESS if the record was added, otherwise
1164 int ldb_add(struct ldb_context *ldb,
1165 const struct ldb_message *message);
1168 Modify the specified attributes of a record
1170 This function modifies a record that is in the database.
1172 \param ldb the context associated with the database (from
1174 \param message the message containing the changes required.
1176 \return result code (LDB_SUCCESS if the record was modified as
1177 requested, otherwise a failure code)
1179 int ldb_modify(struct ldb_context *ldb,
1180 const struct ldb_message *message);
1183 Rename a record in the database
1185 This function renames a record in the database.
1187 \param ldb the context associated with the database (from
1189 \param olddn the DN for the record to be renamed.
1190 \param newdn the new DN
1192 \return result code (LDB_SUCCESS if the record was renamed as
1193 requested, otherwise a failure code)
1195 int ldb_rename(struct ldb_context *ldb, struct ldb_dn *olddn, struct ldb_dn *newdn);
1198 Delete a record from the database
1200 This function deletes a record from the database.
1202 \param ldb the context associated with the database (from
1204 \param dn the DN for the record to be deleted.
1206 \return result code (LDB_SUCCESS if the record was deleted,
1207 otherwise a failure code)
1209 int ldb_delete(struct ldb_context *ldb, struct ldb_dn *dn);
1212 The default async extended operation callback function
1214 \param req the request we are callback of
1215 \param ares a single reply from the async core
1217 \return result code (LDB_SUCCESS on success, or a failure code)
1219 \note this function expects req->context to always be an struct ldb_result pointer
1220 AND a talloc context, this function will steal on the context each message
1221 from the ares reply passed on by the async core so that in the end all the
1222 messages will be in the context (ldb_result) memory tree.
1223 Freeing the passed context (ldb_result tree) will free all the resources
1224 (the request need to be freed separately and the result doe not depend on the
1225 request that can be freed as sson as the search request is finished)
1228 int ldb_extended_default_callback(struct ldb_request *req, struct ldb_reply *ares);
1232 Helper function to build a extended request
1234 \param ret_req the request structure is returned here (talloced on mem_ctx)
1235 \param ldb the context associated with the database (from ldb_init())
1236 \param mem_ctx a talloc memory context (used as parent of ret_req)
1237 \param oid the OID of the extended operation.
1238 \param data a void pointer a the extended operation specific parameters,
1239 it needs to be NULL or a valid talloc pointer! talloc_get_type() will be used on it
1240 \param controls an array of controls
1241 \param context the callback function context
1242 \param the callback function to handle the async replies
1243 \param the parent request if any
1245 \return result code (LDB_SUCCESS on success, or a failure code)
1247 int ldb_build_extended_req(struct ldb_request **ret_req,
1248 struct ldb_context *ldb,
1249 TALLOC_CTX *mem_ctx,
1251 void *data,/* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
1252 struct ldb_control **controls,
1254 ldb_request_callback_t callback,
1255 struct ldb_request *parent);
1258 call an extended operation
1260 This function deletes a record from the database.
1262 \param ldb the context associated with the database (from ldb_init())
1263 \param oid the OID of the extended operation.
1264 \param data a void pointer a the extended operation specific parameters,
1265 it needs to be NULL or a valid talloc pointer! talloc_get_type() will be used on it
1266 \param res the result of the extended operation
1268 \return result code (LDB_SUCCESS if the extended operation returned fine,
1269 otherwise a failure code)
1271 int ldb_extended(struct ldb_context *ldb,
1273 void *data,/* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
1274 struct ldb_result **res);
1277 Obtain current/next database sequence number
1279 int ldb_sequence_number(struct ldb_context *ldb, enum ldb_sequence_type type, uint64_t *seq_num);
1284 int ldb_transaction_start(struct ldb_context *ldb);
1287 commit a transaction
1289 int ldb_transaction_commit(struct ldb_context *ldb);
1292 cancel a transaction
1294 int ldb_transaction_cancel(struct ldb_context *ldb);
1298 return extended error information from the last call
1300 const char *ldb_errstring(struct ldb_context *ldb);
1303 return a string explaining what a ldb error constant meancs
1305 const char *ldb_strerror(int ldb_err);
1308 setup the default utf8 functions
1309 FIXME: these functions do not yet handle utf8
1311 void ldb_set_utf8_default(struct ldb_context *ldb);
1316 \param ldb the ldb context
1317 \param mem_ctx the memory context to allocate the result string
1319 \param s the string that is to be folded
1320 \return a copy of the string, converted to upper case
1322 \note The default function is not yet UTF8 aware. Provide your own
1323 set of functions through ldb_set_utf8_fns()
1325 char *ldb_casefold(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *s, size_t n);
1328 Check the attribute name is valid according to rfc2251
1329 \param s the string to check
1331 \return 1 if the name is ok
1333 int ldb_valid_attr_name(const char *s);
1336 ldif manipulation functions
1340 Write an LDIF message
1342 This function writes an LDIF message using a caller supplied write
1345 \param ldb the ldb context (from ldb_init())
1346 \param fprintf_fn a function pointer for the write function. This must take
1347 a private data pointer, followed by a format string, and then a variable argument
1349 \param private_data pointer that will be provided back to the write
1350 function. This is useful for maintaining state or context.
1351 \param ldif the message to write out
1353 \return the total number of bytes written, or an error code as returned
1354 from the write function.
1356 \sa ldb_ldif_write_file for a more convenient way to write to a
1359 \sa ldb_ldif_read for the reader equivalent to this function.
1361 int ldb_ldif_write(struct ldb_context *ldb,
1362 int (*fprintf_fn)(void *, const char *, ...) PRINTF_ATTRIBUTE(2,3),
1364 const struct ldb_ldif *ldif);
1367 Clean up an LDIF message
1369 This function cleans up a LDIF message read using ldb_ldif_read()
1370 or related functions (such as ldb_ldif_read_string() and
1371 ldb_ldif_read_file().
1373 \param ldb the ldb context (from ldb_init())
1374 \param msg the message to clean up and free
1377 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *msg);
1380 Read an LDIF message
1382 This function creates an LDIF message using a caller supplied read
1385 \param ldb the ldb context (from ldb_init())
1386 \param fgetc_fn a function pointer for the read function. This must
1387 take a private data pointer, and must return a pointer to an
1388 integer corresponding to the next byte read (or EOF if there is no
1389 more data to be read).
1390 \param private_data pointer that will be provided back to the read
1391 function. This is udeful for maintaining state or context.
1393 \return the LDIF message that has been read in
1395 \note You must free the LDIF message when no longer required, using
1396 ldb_ldif_read_free().
1398 \sa ldb_ldif_read_file for a more convenient way to read from a
1401 \sa ldb_ldif_read_string for a more convenient way to read from a
1402 string (char array).
1404 \sa ldb_ldif_write for the writer equivalent to this function.
1406 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
1407 int (*fgetc_fn)(void *), void *private_data);
1410 Read an LDIF message from a file
1412 This function reads the next LDIF message from the contents of a
1413 file stream. If you want to get all of the LDIF messages, you will
1414 need to repeatedly call this function, until it returns NULL.
1416 \param ldb the ldb context (from ldb_init())
1417 \param f the file stream to read from (typically from fdopen())
1419 \sa ldb_ldif_read_string for an equivalent function that will read
1420 from a string (char array).
1422 \sa ldb_ldif_write_file for the writer equivalent to this function.
1425 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
1428 Read an LDIF message from a string
1430 This function reads the next LDIF message from the contents of a char
1431 array. If you want to get all of the LDIF messages, you will need
1432 to repeatedly call this function, until it returns NULL.
1434 \param ldb the ldb context (from ldb_init())
1435 \param s pointer to the char array to read from
1437 \sa ldb_ldif_read_file for an equivalent function that will read
1440 \sa ldb_ldif_write for a more general (arbitrary read function)
1441 version of this function.
1443 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
1446 Write an LDIF message to a file
1448 \param ldb the ldb context (from ldb_init())
1449 \param f the file stream to write to (typically from fdopen())
1450 \param msg the message to write out
1452 \return the total number of bytes written, or a negative error code
1454 \sa ldb_ldif_read_file for the reader equivalent to this function.
1456 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
1459 Write an LDIF message to a string
1461 \param ldb the ldb context (from ldb_init())
1462 \param mem_ctx the talloc context on which to attach the string)
1463 \param msg the message to write out
1465 \return the string containing the LDIF, or NULL on error
1467 \sa ldb_ldif_read_string for the reader equivalent to this function.
1469 char * ldb_ldif_write_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
1470 const struct ldb_ldif *msg);
1474 Produce a string form of an ldb message
1476 convenient function to turn a ldb_message into a string. Useful for
1479 char *ldb_ldif_message_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
1480 enum ldb_changetype changetype,
1481 const struct ldb_message *msg);
1485 Base64 encode a buffer
1487 \param mem_ctx the memory context that the result is allocated
1489 \param buf pointer to the array that is to be encoded
1490 \param len the number of elements in the array to be encoded
1492 \return pointer to an array containing the encoded data
1494 \note The caller is responsible for freeing the result
1496 char *ldb_base64_encode(TALLOC_CTX *mem_ctx, const char *buf, int len);
1499 Base64 decode a buffer
1501 This function decodes a base64 encoded string in place.
1503 \param s the string to decode.
1505 \return the length of the returned (decoded) string.
1507 \note the string is null terminated, but the null terminator is not
1508 included in the length.
1510 int ldb_base64_decode(char *s);
1512 /* The following definitions come from lib/ldb/common/ldb_dn.c */
1515 Get the linear form of a DN (without any extended components)
1517 \param dn The DN to linearize
1520 const char *ldb_dn_get_linearized(struct ldb_dn *dn);
1523 Allocate a copy of the linear form of a DN (without any extended components) onto the supplied memory context
1525 \param dn The DN to linearize
1526 \param mem_ctx TALLOC context to return result on
1529 char *ldb_dn_alloc_linearized(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1532 Get the linear form of a DN (with any extended components)
1534 \param mem_ctx TALLOC context to return result on
1535 \param dn The DN to linearize
1536 \param mode Style of extended DN to return (0 is HEX representation of binary form, 1 is a string form)
1538 char *ldb_dn_get_extended_linearized(void *mem_ctx, struct ldb_dn *dn, int mode);
1539 const struct ldb_val *ldb_dn_get_extended_component(struct ldb_dn *dn, const char *name);
1540 int ldb_dn_set_extended_component(struct ldb_dn *dn, const char *name, const struct ldb_val *val);
1542 void ldb_dn_remove_extended_components(struct ldb_dn *dn);
1543 bool ldb_dn_has_extended(struct ldb_dn *dn);
1545 int ldb_dn_extended_add_syntax(struct ldb_context *ldb,
1547 const struct ldb_dn_extended_syntax *syntax);
1550 Allocate a new DN from a string
1552 \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1553 \param dn The new DN
1555 \note The DN will not be parsed at this time. Use ldb_dn_validate to tell if the DN is syntacticly correct
1558 struct ldb_dn *ldb_dn_new(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *dn);
1560 Allocate a new DN from a printf style format string and arguments
1562 \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1563 \param new_fms The new DN as a format string (plus arguments)
1565 \note The DN will not be parsed at this time. Use ldb_dn_validate to tell if the DN is syntacticly correct
1568 struct ldb_dn *ldb_dn_new_fmt(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *new_fmt, ...) PRINTF_ATTRIBUTE(3,4);
1570 Allocate a new DN from a struct ldb_val (useful to avoid buffer overrun)
1572 \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1573 \param dn The new DN
1575 \note The DN will not be parsed at this time. Use ldb_dn_validate to tell if the DN is syntacticly correct
1578 struct ldb_dn *ldb_dn_from_ldb_val(void *mem_ctx, struct ldb_context *ldb, const struct ldb_val *strdn);
1581 Determine if this DN is syntactically valid
1583 \param dn The DN to validate
1586 bool ldb_dn_validate(struct ldb_dn *dn);
1588 char *ldb_dn_escape_value(TALLOC_CTX *mem_ctx, struct ldb_val value);
1589 const char *ldb_dn_get_casefold(struct ldb_dn *dn);
1590 char *ldb_dn_alloc_casefold(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1592 int ldb_dn_compare_base(struct ldb_dn *base, struct ldb_dn *dn);
1593 int ldb_dn_compare(struct ldb_dn *edn0, struct ldb_dn *edn1);
1595 bool ldb_dn_add_base(struct ldb_dn *dn, struct ldb_dn *base);
1596 bool ldb_dn_add_base_fmt(struct ldb_dn *dn, const char *base_fmt, ...) PRINTF_ATTRIBUTE(2,3);
1597 bool ldb_dn_add_child(struct ldb_dn *dn, struct ldb_dn *child);
1598 bool ldb_dn_add_child_fmt(struct ldb_dn *dn, const char *child_fmt, ...) PRINTF_ATTRIBUTE(2,3);
1599 bool ldb_dn_remove_base_components(struct ldb_dn *dn, unsigned int num);
1600 bool ldb_dn_remove_child_components(struct ldb_dn *dn, unsigned int num);
1602 struct ldb_dn *ldb_dn_copy(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1603 struct ldb_dn *ldb_dn_get_parent(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1604 char *ldb_dn_canonical_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1605 char *ldb_dn_canonical_ex_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1606 int ldb_dn_get_comp_num(struct ldb_dn *dn);
1607 const char *ldb_dn_get_component_name(struct ldb_dn *dn, unsigned int num);
1608 const struct ldb_val *ldb_dn_get_component_val(struct ldb_dn *dn, unsigned int num);
1609 const char *ldb_dn_get_rdn_name(struct ldb_dn *dn);
1610 const struct ldb_val *ldb_dn_get_rdn_val(struct ldb_dn *dn);
1611 int ldb_dn_set_component(struct ldb_dn *dn, int num, const char *name, const struct ldb_val val);
1613 bool ldb_dn_is_valid(struct ldb_dn *dn);
1614 bool ldb_dn_is_special(struct ldb_dn *dn);
1615 bool ldb_dn_check_special(struct ldb_dn *dn, const char *check);
1616 bool ldb_dn_is_null(struct ldb_dn *dn);
1620 Compare two attributes
1622 This function compares to attribute names. Note that this is a
1623 case-insensitive comparison.
1625 \param a the first attribute name to compare
1626 \param b the second attribute name to compare
1628 \return 0 if the attribute names are the same, or only differ in
1629 case; non-zero if there are any differences
1631 attribute names are restricted by rfc2251 so using
1632 strcasecmp and toupper here is ok.
1635 #define ldb_attr_cmp(a, b) strcasecmp(a, b)
1636 char *ldb_attr_casefold(TALLOC_CTX *mem_ctx, const char *s);
1637 int ldb_attr_dn(const char *attr);
1640 Create an empty message
1642 \param mem_ctx the memory context to create in. You can pass NULL
1643 to get the top level context, however the ldb context (from
1644 ldb_init()) may be a better choice
1646 struct ldb_message *ldb_msg_new(TALLOC_CTX *mem_ctx);
1649 Find an element within an message
1651 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg,
1652 const char *attr_name);
1655 Compare two ldb_val values
1657 \param v1 first ldb_val structure to be tested
1658 \param v2 second ldb_val structure to be tested
1660 \return 1 for a match, 0 if there is any difference
1662 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
1665 find a value within an ldb_message_element
1667 \param el the element to search
1668 \param val the value to search for
1670 \note This search is case sensitive
1672 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el,
1673 struct ldb_val *val);
1676 add a new empty element to a ldb_message
1678 int ldb_msg_add_empty(struct ldb_message *msg,
1679 const char *attr_name,
1681 struct ldb_message_element **return_el);
1684 add a element to a ldb_message
1686 int ldb_msg_add(struct ldb_message *msg,
1687 const struct ldb_message_element *el,
1689 int ldb_msg_add_value(struct ldb_message *msg,
1690 const char *attr_name,
1691 const struct ldb_val *val,
1692 struct ldb_message_element **return_el);
1693 int ldb_msg_add_steal_value(struct ldb_message *msg,
1694 const char *attr_name,
1695 struct ldb_val *val);
1696 int ldb_msg_add_steal_string(struct ldb_message *msg,
1697 const char *attr_name, char *str);
1698 int ldb_msg_add_string(struct ldb_message *msg,
1699 const char *attr_name, const char *str);
1700 int ldb_msg_add_fmt(struct ldb_message *msg,
1701 const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
1704 compare two message elements - return 0 on match
1706 int ldb_msg_element_compare(struct ldb_message_element *el1,
1707 struct ldb_message_element *el2);
1708 int ldb_msg_element_compare_name(struct ldb_message_element *el1,
1709 struct ldb_message_element *el2);
1712 Find elements in a message.
1714 This function finds elements and converts to a specific type, with
1715 a give default value if not found. Assumes that elements are
1718 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
1719 int ldb_msg_find_attr_as_int(const struct ldb_message *msg,
1720 const char *attr_name,
1722 unsigned int ldb_msg_find_attr_as_uint(const struct ldb_message *msg,
1723 const char *attr_name,
1724 unsigned int default_value);
1725 int64_t ldb_msg_find_attr_as_int64(const struct ldb_message *msg,
1726 const char *attr_name,
1727 int64_t default_value);
1728 uint64_t ldb_msg_find_attr_as_uint64(const struct ldb_message *msg,
1729 const char *attr_name,
1730 uint64_t default_value);
1731 double ldb_msg_find_attr_as_double(const struct ldb_message *msg,
1732 const char *attr_name,
1733 double default_value);
1734 int ldb_msg_find_attr_as_bool(const struct ldb_message *msg,
1735 const char *attr_name,
1737 const char *ldb_msg_find_attr_as_string(const struct ldb_message *msg,
1738 const char *attr_name,
1739 const char *default_value);
1741 struct ldb_dn *ldb_msg_find_attr_as_dn(struct ldb_context *ldb,
1742 TALLOC_CTX *mem_ctx,
1743 const struct ldb_message *msg,
1744 const char *attr_name);
1746 void ldb_msg_sort_elements(struct ldb_message *msg);
1748 struct ldb_message *ldb_msg_copy_shallow(TALLOC_CTX *mem_ctx,
1749 const struct ldb_message *msg);
1750 struct ldb_message *ldb_msg_copy(TALLOC_CTX *mem_ctx,
1751 const struct ldb_message *msg);
1753 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb,
1754 const struct ldb_message *msg);
1757 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb,
1758 struct ldb_message *msg1,
1759 struct ldb_message *msg2);
1761 int ldb_msg_check_string_attribute(const struct ldb_message *msg,
1766 Integrity check an ldb_message
1768 This function performs basic sanity / integrity checks on an
1771 \param ldb context in which to perform the checks
1772 \param msg the message to check
1774 \return LDB_SUCCESS if the message is OK, or a non-zero error code
1775 (one of LDB_ERR_INVALID_DN_SYNTAX, LDB_ERR_ENTRY_ALREADY_EXISTS or
1776 LDB_ERR_INVALID_ATTRIBUTE_SYNTAX) if there is a problem with a
1779 int ldb_msg_sanity_check(struct ldb_context *ldb,
1780 const struct ldb_message *msg);
1783 Duplicate an ldb_val structure
1785 This function copies an ldb value structure.
1787 \param mem_ctx the memory context that the duplicated value will be
1789 \param v the ldb_val to be duplicated.
1791 \return the duplicated ldb_val structure.
1793 struct ldb_val ldb_val_dup(TALLOC_CTX *mem_ctx, const struct ldb_val *v);
1796 this allows the user to set a debug function for error reporting
1798 int ldb_set_debug(struct ldb_context *ldb,
1799 void (*debug)(void *context, enum ldb_debug_level level,
1800 const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0),
1804 this allows the user to set custom utf8 function for error reporting
1806 void ldb_set_utf8_fns(struct ldb_context *ldb,
1808 char *(*casefold)(void *, void *, const char *, size_t n));
1811 this sets up debug to print messages on stderr
1813 int ldb_set_debug_stderr(struct ldb_context *ldb);
1815 /* control backend specific opaque values */
1816 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
1817 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
1819 const char **ldb_attr_list_copy(TALLOC_CTX *mem_ctx, const char * const *attrs);
1820 const char **ldb_attr_list_copy_add(TALLOC_CTX *mem_ctx, const char * const *attrs, const char *new_attr);
1821 int ldb_attr_in_list(const char * const *attrs, const char *attr);
1823 int ldb_msg_rename_attr(struct ldb_message *msg, const char *attr, const char *replace);
1824 int ldb_msg_copy_attr(struct ldb_message *msg, const char *attr, const char *replace);
1825 void ldb_msg_remove_attr(struct ldb_message *msg, const char *attr);
1826 void ldb_msg_remove_element(struct ldb_message *msg, struct ldb_message_element *el);
1829 void ldb_parse_tree_attr_replace(struct ldb_parse_tree *tree,
1831 const char *replace);
1835 Convert a time structure to a string
1837 This function converts a time_t structure to an LDAP formatted
1838 GeneralizedTime string.
1840 \param mem_ctx the memory context to allocate the return string in
1841 \param t the time structure to convert
1843 \return the formatted string, or NULL if the time structure could
1846 char *ldb_timestring(TALLOC_CTX *mem_ctx, time_t t);
1849 Convert a string to a time structure
1851 This function converts an LDAP formatted GeneralizedTime string
1852 to a time_t structure.
1854 \param s the string to convert
1856 \return the time structure, or 0 if the string cannot be converted
1858 time_t ldb_string_to_time(const char *s);
1861 Convert a time structure to a string
1863 This function converts a time_t structure to an LDAP formatted
1866 \param mem_ctx the memory context to allocate the return string in
1867 \param t the time structure to convert
1869 \return the formatted string, or NULL if the time structure could
1872 char *ldb_timestring_utc(TALLOC_CTX *mem_ctx, time_t t);
1875 Convert a string to a time structure
1877 This function converts an LDAP formatted UTCTime string
1878 to a time_t structure.
1880 \param s the string to convert
1882 \return the time structure, or 0 if the string cannot be converted
1884 time_t ldb_string_utc_to_time(const char *s);
1887 void ldb_qsort (void *const pbase, size_t total_elems, size_t size, void *opaque, ldb_qsort_cmp_fn_t cmp);
1891 Convert an array of string represention of a control into an array of ldb_control structures
1893 \param ldb LDB context
1894 \param mem_ctx TALLOC context to return result on, and to allocate error_string on
1895 \param control_strings Array of string-formatted controls
1897 \return array of ldb_control elements
1899 struct ldb_control **ldb_parse_control_strings(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char **control_strings);
1902 return the ldb flags
1904 unsigned int ldb_get_flags(struct ldb_context *ldb);