Merge branch 'master' of ssh://git.samba.org/data/git/samba
[ira/wip.git] / source4 / lib / ldb / include / ldb.h
1 /* 
2    ldb database library
3
4    Copyright (C) Andrew Tridgell  2004
5    Copyright (C) Stefan Metzmacher  2004
6    Copyright (C) Simo Sorce  2005-2006
7
8      ** NOTE! The following LGPL license applies to the ldb
9      ** library. This does NOT imply that all of Samba is released
10      ** under the LGPL
11    
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.
16
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.
21
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/>.
24 */
25
26 /*
27  *  Name: ldb
28  *
29  *  Component: ldb header
30  *
31  *  Description: defines for base ldb API
32  *
33  *  Author: Andrew Tridgell
34  *  Author: Stefan Metzmacher
35  */
36
37 /**
38    \file ldb.h Samba's ldb database
39
40    This header file provides the main API for ldb.
41 */
42
43 #ifndef _LDB_H_
44
45 /*! \cond DOXYGEN_IGNORE */
46 #define _LDB_H_ 1
47 /*! \endcond */
48
49 #ifndef bool
50 typedef int bool;
51 #endif
52 #ifndef true
53 #define true 1
54 #endif
55 #ifndef false
56 #define false 0
57 #endif
58
59 #include "talloc.h"
60 #include "tevent.h"
61 #include "ldb_errors.h"
62
63 /*
64   major restrictions as compared to normal LDAP:
65
66      - each record must have a unique key field
67      - the key must be representable as a NULL terminated C string and may not 
68        contain a comma or braces
69
70   major restrictions as compared to tdb:
71
72      - no explicit locking calls, but we have transactions when using ldb_tdb
73
74 */
75
76 #ifndef ldb_val
77 /**
78    Result value
79
80    An individual lump of data in a result comes in this format. The
81    pointer will usually be to a UTF-8 string if the application is
82    sensible, but it can be to anything you like, including binary data
83    blobs of arbitrary size.
84
85    \note the data is null (0x00) terminated, but the length does not
86    include the terminator. 
87 */
88 struct ldb_val {
89         uint8_t *data; /*!< result data */
90         size_t length; /*!< length of data */
91 };
92 #endif
93
94 /*! \cond DOXYGEN_IGNORE */
95 #ifndef PRINTF_ATTRIBUTE
96 #define PRINTF_ATTRIBUTE(a,b)
97 #endif
98 /*! \endcond */
99
100 /* opaque ldb_dn structures, see ldb_dn.c for internals */
101 struct ldb_dn_component;
102 struct ldb_dn;
103
104 /**
105  There are a number of flags that are used with ldap_modify() in
106  ldb_message_element.flags fields. The LDA_FLAGS_MOD_ADD,
107  LDA_FLAGS_MOD_DELETE and LDA_FLAGS_MOD_REPLACE flags are used in
108  ldap_modify() calls to specify whether attributes are being added,
109  deleted or modified respectively.
110 */
111 #define LDB_FLAG_MOD_MASK  0x3
112
113 /**
114    Flag value used in ldap_modify() to indicate that attributes are
115    being added.
116
117    \sa LDB_FLAG_MOD_MASK
118 */
119 #define LDB_FLAG_MOD_ADD     1
120
121 /**
122    Flag value used in ldap_modify() to indicate that attributes are
123    being replaced.
124
125    \sa LDB_FLAG_MOD_MASK
126 */
127 #define LDB_FLAG_MOD_REPLACE 2
128
129 /**
130    Flag value used in ldap_modify() to indicate that attributes are
131    being deleted.
132
133    \sa LDB_FLAG_MOD_MASK
134 */
135 #define LDB_FLAG_MOD_DELETE  3
136
137 /**
138   OID for logic AND comaprison.
139
140   This is the well known object ID for a logical AND comparitor.
141 */
142 #define LDB_OID_COMPARATOR_AND  "1.2.840.113556.1.4.803"
143
144 /**
145   OID for logic OR comparison.
146
147   This is the well known object ID for a logical OR comparitor.
148 */
149 #define LDB_OID_COMPARATOR_OR   "1.2.840.113556.1.4.804"
150
151 /**
152   results are given back as arrays of ldb_message_element
153 */
154 struct ldb_message_element {
155         unsigned int flags;
156         const char *name;
157         unsigned int num_values;
158         struct ldb_val *values;
159 };
160
161
162 /**
163   a ldb_message represents all or part of a record. It can contain an arbitrary
164   number of elements. 
165 */
166 struct ldb_message {
167         struct ldb_dn *dn;
168         unsigned int num_elements;
169         struct ldb_message_element *elements;
170 };
171
172 enum ldb_changetype {
173         LDB_CHANGETYPE_NONE=0,
174         LDB_CHANGETYPE_ADD,
175         LDB_CHANGETYPE_DELETE,
176         LDB_CHANGETYPE_MODIFY
177 };
178
179 /**
180   LDIF record
181
182   This structure contains a LDIF record, as returned from ldif_read()
183   and equivalent functions.
184 */
185 struct ldb_ldif {
186         enum ldb_changetype changetype; /*!< The type of change */
187         struct ldb_message *msg;  /*!< The changes */
188 };
189
190 enum ldb_scope {LDB_SCOPE_DEFAULT=-1, 
191                 LDB_SCOPE_BASE=0, 
192                 LDB_SCOPE_ONELEVEL=1,
193                 LDB_SCOPE_SUBTREE=2};
194
195 struct ldb_context;
196 struct tevent_context;
197
198 /* debugging uses one of the following levels */
199 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR, 
200                       LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
201
202 /**
203   the user can optionally supply a debug function. The function
204   is based on the vfprintf() style of interface, but with the addition
205   of a severity level
206 */
207 struct ldb_debug_ops {
208         void (*debug)(void *context, enum ldb_debug_level level, 
209                       const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0);
210         void *context;
211 };
212
213 /**
214   The user can optionally supply a custom utf8 functions,
215   to handle comparisons and casefolding.
216 */
217 struct ldb_utf8_fns {
218         void *context;
219         char *(*casefold)(void *context, TALLOC_CTX *mem_ctx, const char *s, size_t n);
220 };
221
222 /**
223    Flag value for database connection mode.
224
225    If LDB_FLG_RDONLY is used in ldb_connect, then the database will be
226    opened read-only, if possible.
227 */
228 #define LDB_FLG_RDONLY 1
229
230 /**
231    Flag value for database connection mode.
232
233    If LDB_FLG_NOSYNC is used in ldb_connect, then the database will be
234    opened without synchronous operations, if possible.
235 */
236 #define LDB_FLG_NOSYNC 2
237
238 /**
239    Flag value to specify autoreconnect mode.
240
241    If LDB_FLG_RECONNECT is used in ldb_connect, then the backend will
242    be opened in a way that makes it try to auto reconnect if the
243    connection is dropped (actually make sense only with ldap).
244 */
245 #define LDB_FLG_RECONNECT 4
246
247 /**
248    Flag to tell backends not to use mmap
249 */
250 #define LDB_FLG_NOMMAP 8
251
252 /*
253    structures for ldb_parse_tree handling code
254 */
255 enum ldb_parse_op { LDB_OP_AND=1, LDB_OP_OR=2, LDB_OP_NOT=3,
256                     LDB_OP_EQUALITY=4, LDB_OP_SUBSTRING=5,
257                     LDB_OP_GREATER=6, LDB_OP_LESS=7, LDB_OP_PRESENT=8,
258                     LDB_OP_APPROX=9, LDB_OP_EXTENDED=10 };
259
260 struct ldb_parse_tree {
261         enum ldb_parse_op operation;
262         union {
263                 struct {
264                         struct ldb_parse_tree *child;
265                 } isnot;
266                 struct {
267                         const char *attr;
268                         struct ldb_val value;
269                 } equality;
270                 struct {
271                         const char *attr;
272                         int start_with_wildcard;
273                         int end_with_wildcard;
274                         struct ldb_val **chunks;
275                 } substring;
276                 struct {
277                         const char *attr;
278                 } present;
279                 struct {
280                         const char *attr;
281                         struct ldb_val value;
282                 } comparison;
283                 struct {
284                         const char *attr;
285                         int dnAttributes;
286                         char *rule_id;
287                         struct ldb_val value;
288                 } extended;
289                 struct {
290                         unsigned int num_elements;
291                         struct ldb_parse_tree **elements;
292                 } list;
293         } u;
294 };
295
296 struct ldb_parse_tree *ldb_parse_tree(TALLOC_CTX *mem_ctx, const char *s);
297 char *ldb_filter_from_tree(TALLOC_CTX *mem_ctx, struct ldb_parse_tree *tree);
298
299 /**
300    Encode a binary blob
301
302    This function encodes a binary blob using the encoding rules in RFC
303    2254 (Section 4). This function also escapes any non-printable
304    characters.
305
306    \param mem_ctx the memory context to allocate the return string in.
307    \param val the (potentially) binary data to be encoded
308
309    \return the encoded data as a null terminated string
310
311    \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>.
312 */
313 char *ldb_binary_encode(TALLOC_CTX *mem_ctx, struct ldb_val val);
314
315 /**
316    Encode a string
317
318    This function encodes a string using the encoding rules in RFC 2254
319    (Section 4). This function also escapes any non-printable
320    characters.
321
322    \param mem_ctx the memory context to allocate the return string in.
323    \param string the string to be encoded
324
325    \return the encoded data as a null terminated string
326
327    \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>.
328 */
329 char *ldb_binary_encode_string(TALLOC_CTX *mem_ctx, const char *string);
330
331 /*
332   functions for controlling attribute handling
333 */
334 typedef int (*ldb_attr_handler_t)(struct ldb_context *, TALLOC_CTX *mem_ctx, const struct ldb_val *, struct ldb_val *);
335 typedef int (*ldb_attr_comparison_t)(struct ldb_context *, TALLOC_CTX *mem_ctx, const struct ldb_val *, const struct ldb_val *);
336
337 /*
338   attribute handler structure
339
340   attr                  -> The attribute name
341   ldif_read_fn          -> convert from ldif to binary format
342   ldif_write_fn         -> convert from binary to ldif format
343   canonicalise_fn       -> canonicalise a value, for use by indexing and dn construction
344   comparison_fn         -> compare two values
345 */
346
347 struct ldb_schema_syntax {
348         const char *name;
349         ldb_attr_handler_t ldif_read_fn;
350         ldb_attr_handler_t ldif_write_fn;
351         ldb_attr_handler_t canonicalise_fn;
352         ldb_attr_comparison_t comparison_fn;
353 };
354
355 struct ldb_schema_attribute {
356         const char *name;
357         unsigned flags;
358         const struct ldb_schema_syntax *syntax;
359 };
360
361 const struct ldb_schema_attribute *ldb_schema_attribute_by_name(struct ldb_context *ldb,
362                                                                 const char *name);
363
364 struct ldb_dn_extended_syntax {
365         const char *name;
366         ldb_attr_handler_t read_fn;
367         ldb_attr_handler_t write_clear_fn;
368         ldb_attr_handler_t write_hex_fn;
369 };
370
371 const struct ldb_dn_extended_syntax *ldb_dn_extended_syntax_by_name(struct ldb_context *ldb,
372                                                                     const char *name);
373
374 /**
375    The attribute is not returned by default
376 */
377 #define LDB_ATTR_FLAG_HIDDEN       (1<<0) 
378
379 /* the attribute handler name should be freed when released */
380 #define LDB_ATTR_FLAG_ALLOCATED    (1<<1) 
381
382 /**
383    The attribute is supplied by the application and should not be removed
384 */
385 #define LDB_ATTR_FLAG_FIXED        (1<<2) 
386
387 /**
388   LDAP attribute syntax for a DN
389
390   This is the well-known LDAP attribute syntax for a DN.
391
392   See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 
393 */
394 #define LDB_SYNTAX_DN                   "1.3.6.1.4.1.1466.115.121.1.12"
395
396 /**
397   LDAP attribute syntax for a Directory String
398
399   This is the well-known LDAP attribute syntax for a Directory String.
400
401   \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 
402 */
403 #define LDB_SYNTAX_DIRECTORY_STRING     "1.3.6.1.4.1.1466.115.121.1.15"
404
405 /**
406   LDAP attribute syntax for an integer
407
408   This is the well-known LDAP attribute syntax for an integer.
409
410   See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 
411 */
412 #define LDB_SYNTAX_INTEGER              "1.3.6.1.4.1.1466.115.121.1.27"
413
414 /**
415   LDAP attribute syntax for an octet string
416
417   This is the well-known LDAP attribute syntax for an octet string.
418
419   See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 
420 */
421 #define LDB_SYNTAX_OCTET_STRING         "1.3.6.1.4.1.1466.115.121.1.40"
422
423 /**
424   LDAP attribute syntax for UTC time.
425
426   This is the well-known LDAP attribute syntax for a UTC time.
427
428   See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 
429 */
430 #define LDB_SYNTAX_UTC_TIME             "1.3.6.1.4.1.1466.115.121.1.53"
431
432 #define LDB_SYNTAX_OBJECTCLASS          "LDB_SYNTAX_OBJECTCLASS"
433
434 /* sorting helpers */
435 typedef int (*ldb_qsort_cmp_fn_t) (void *v1, void *v2, void *opaque);
436
437 /**
438    OID for the paged results control. This control is included in the
439    searchRequest and searchResultDone messages as part of the controls
440    field of the LDAPMessage, as defined in Section 4.1.12 of
441    LDAP v3. 
442
443    \sa <a href="http://www.ietf.org/rfc/rfc2696.txt">RFC 2696</a>.
444 */
445 #define LDB_CONTROL_PAGED_RESULTS_OID   "1.2.840.113556.1.4.319"
446
447 /**
448    OID for specifying the returned elements of the ntSecurityDescriptor
449
450    \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>
451 */
452 #define LDB_CONTROL_SD_FLAGS_OID        "1.2.840.113556.1.4.801"
453
454 /**
455    OID for specifying an advanced scope for the search (one partition)
456
457    \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>
458 */
459 #define LDB_CONTROL_DOMAIN_SCOPE_OID    "1.2.840.113556.1.4.1339"
460
461 /**
462    OID for specifying an advanced scope for a search
463
464    \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>
465 */
466 #define LDB_CONTROL_SEARCH_OPTIONS_OID  "1.2.840.113556.1.4.1340"
467
468 /**
469    OID for notification
470
471    \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>
472 */
473 #define LDB_CONTROL_NOTIFICATION_OID    "1.2.840.113556.1.4.528"
474
475 /**
476    OID for getting deleted objects
477
478    \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>
479 */
480 #define LDB_CONTROL_SHOW_DELETED_OID    "1.2.840.113556.1.4.417"
481
482 /**
483    OID for extended DN
484
485    \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>
486 */
487 #define LDB_CONTROL_EXTENDED_DN_OID     "1.2.840.113556.1.4.529"
488
489 /**
490    OID for LDAP server sort result extension.
491
492    This control is included in the searchRequest message as part of
493    the controls field of the LDAPMessage, as defined in Section 4.1.12
494    of LDAP v3. The controlType is set to
495    "1.2.840.113556.1.4.473". The criticality MAY be either TRUE or
496    FALSE (where absent is also equivalent to FALSE) at the client's
497    option.
498
499    \sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
500 */
501 #define LDB_CONTROL_SERVER_SORT_OID     "1.2.840.113556.1.4.473"
502
503 /**
504    OID for LDAP server sort result response extension.
505
506    This control is included in the searchResultDone message as part of
507    the controls field of the LDAPMessage, as defined in Section 4.1.12 of
508    LDAP v3.
509
510    \sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
511 */
512 #define LDB_CONTROL_SORT_RESP_OID       "1.2.840.113556.1.4.474"
513
514 /**
515    OID for LDAP Attribute Scoped Query extension.
516
517    This control is included in SearchRequest or SearchResponse
518    messages as part of the controls field of the LDAPMessage.
519 */
520 #define LDB_CONTROL_ASQ_OID             "1.2.840.113556.1.4.1504"
521
522 /**
523    OID for LDAP Directory Sync extension. 
524
525    This control is included in SearchRequest or SearchResponse
526    messages as part of the controls field of the LDAPMessage.
527 */
528 #define LDB_CONTROL_DIRSYNC_OID         "1.2.840.113556.1.4.841"
529
530
531 /**
532    OID for LDAP Virtual List View Request extension.
533
534    This control is included in SearchRequest messages
535    as part of the controls field of the LDAPMessage.
536 */
537 #define LDB_CONTROL_VLV_REQ_OID         "2.16.840.1.113730.3.4.9"
538
539 /**
540    OID for LDAP Virtual List View Response extension.
541
542    This control is included in SearchResponse messages
543    as part of the controls field of the LDAPMessage.
544 */
545 #define LDB_CONTROL_VLV_RESP_OID        "2.16.840.1.113730.3.4.10"
546
547 /**
548    OID to let modifies don't give an error when adding an existing
549    attribute with the same value or deleting an nonexisting one attribute
550
551    \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>
552 */
553 #define LDB_CONTROL_PERMISSIVE_MODIFY_OID       "1.2.840.113556.1.4.1413"
554
555 /**
556    OID for LDAP Extended Operation START_TLS.
557
558    This Extended operation is used to start a new TLS
559    channel on top of a clear text channel.
560 */
561 #define LDB_EXTENDED_START_TLS_OID      "1.3.6.1.4.1.1466.20037"
562
563 /**
564 */
565 #define LDB_EXTENDED_DYNAMIC_OID        "1.3.6.1.4.1.1466.101.119.1"
566
567 /**
568 */
569 #define LDB_EXTENDED_FAST_BIND_OID      "1.2.840.113556.1.4.1781"
570
571 struct ldb_sd_flags_control {
572         /*
573          * request the owner    0x00000001
574          * request the group    0x00000002
575          * request the DACL     0x00000004
576          * request the SACL     0x00000008
577          */
578         unsigned secinfo_flags;
579 };
580
581 /*
582  * DOMAIN_SCOPE         0x00000001
583  * this limits the search to one partition,
584  * and no referrals will be returned.
585  * (Note this doesn't limit the entries by there
586  *  objectSid belonging to a domain! Builtin and Foreign Sids
587  *  are still returned)
588  *
589  * PHANTOM_ROOT         0x00000002
590  * this search on the whole tree on a domain controller
591  * over multiple partitions without referrals.
592  * (This is the default behavior on the Global Catalog Port)
593  */
594
595 #define LDB_SEARCH_OPTION_DOMAIN_SCOPE 0x00000001
596 #define LDB_SEARCH_OPTION_PHANTOM_ROOT 0x00000002
597
598 struct ldb_search_options_control {
599         unsigned search_options;
600 };
601
602 struct ldb_paged_control {
603         int size;
604         int cookie_len;
605         char *cookie;
606 };
607
608 struct ldb_extended_dn_control {
609         int type;
610 };
611
612 struct ldb_server_sort_control {
613         char *attributeName;
614         char *orderingRule;
615         int reverse;
616 };
617
618 struct ldb_sort_resp_control {
619         int result;
620         char *attr_desc;
621 };
622
623 struct ldb_asq_control {
624         int request;
625         char *source_attribute;
626         int src_attr_len;
627         int result;
628 };
629
630 struct ldb_dirsync_control {
631         int flags;
632         int max_attributes;
633         int cookie_len;
634         char *cookie;
635 };
636
637 struct ldb_vlv_req_control {
638         int beforeCount;
639         int afterCount;
640         int type;
641         union {
642                 struct {
643                         int offset;
644                         int contentCount;
645                 } byOffset;
646                 struct {
647                         int value_len;
648                         char *value;
649                 } gtOrEq;
650         } match;
651         int ctxid_len;
652         char *contextId;
653 };
654
655 struct ldb_vlv_resp_control {
656         int targetPosition;
657         int contentCount;
658         int vlv_result;
659         int ctxid_len;
660         char *contextId;
661 };
662
663 struct ldb_control {
664         const char *oid;
665         int critical;
666         void *data;
667 };
668
669 enum ldb_request_type {
670         LDB_SEARCH,
671         LDB_ADD,
672         LDB_MODIFY,
673         LDB_DELETE,
674         LDB_RENAME,
675         LDB_EXTENDED,
676         LDB_REQ_REGISTER_CONTROL,
677         LDB_REQ_REGISTER_PARTITION
678 };
679
680 enum ldb_reply_type {
681         LDB_REPLY_ENTRY,
682         LDB_REPLY_REFERRAL,
683         LDB_REPLY_DONE
684 };
685
686 enum ldb_wait_type {
687         LDB_WAIT_ALL,
688         LDB_WAIT_NONE
689 };
690
691 enum ldb_state {
692         LDB_ASYNC_INIT,
693         LDB_ASYNC_PENDING,
694         LDB_ASYNC_DONE
695 };
696
697 struct ldb_extended {
698         const char *oid;
699         void *data; /* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
700 };
701
702 #define LDB_EXTENDED_SEQUENCE_NUMBER    "1.3.6.1.4.1.7165.4.4.3"
703
704 enum ldb_sequence_type {
705         LDB_SEQ_HIGHEST_SEQ,
706         LDB_SEQ_HIGHEST_TIMESTAMP,
707         LDB_SEQ_NEXT
708 };
709
710 #define LDB_SEQ_GLOBAL_SEQUENCE    0x01
711 #define LDB_SEQ_TIMESTAMP_SEQUENCE 0x02
712
713 struct ldb_seqnum_request {
714         enum ldb_sequence_type type;
715 };
716
717 struct ldb_seqnum_result {
718         uint64_t seq_num;
719         uint32_t flags;
720 };
721
722 struct ldb_result {
723         unsigned int count;
724         struct ldb_message **msgs;
725         struct ldb_extended *extended;
726         struct ldb_control **controls;
727         char **refs;
728 };
729
730 struct ldb_reply {
731         int error;
732         enum ldb_reply_type type;
733         struct ldb_message *message;
734         struct ldb_extended *response;
735         struct ldb_control **controls;
736         char *referral;
737 };
738
739 struct ldb_request;
740 struct ldb_handle;
741
742 struct ldb_search {
743         struct ldb_dn *base;
744         enum ldb_scope scope;
745         struct ldb_parse_tree *tree;
746         const char * const *attrs;
747         struct ldb_result *res;
748 };
749
750 struct ldb_add {
751         const struct ldb_message *message;
752 };
753
754 struct ldb_modify {
755         const struct ldb_message *message;
756 };
757
758 struct ldb_delete {
759         struct ldb_dn *dn;
760 };
761
762 struct ldb_rename {
763         struct ldb_dn *olddn;
764         struct ldb_dn *newdn;
765 };
766
767 struct ldb_register_control {
768         const char *oid;
769 };
770
771 struct ldb_register_partition {
772         struct ldb_dn *dn;
773 };
774
775 typedef int (*ldb_request_callback_t)(struct ldb_request *, struct ldb_reply *);
776
777 struct ldb_request {
778
779         enum ldb_request_type operation;
780
781         union {
782                 struct ldb_search search;
783                 struct ldb_add    add;
784                 struct ldb_modify mod;
785                 struct ldb_delete del;
786                 struct ldb_rename rename;
787                 struct ldb_extended extended;
788                 struct ldb_register_control reg_control;
789                 struct ldb_register_partition reg_partition;
790         } op;
791
792         struct ldb_control **controls;
793
794         void *context;
795         ldb_request_callback_t callback;
796
797         int timeout;
798         time_t starttime;
799         struct ldb_handle *handle;
800 };
801
802 int ldb_request(struct ldb_context *ldb, struct ldb_request *request);
803 int ldb_request_done(struct ldb_request *req, int status);
804 bool ldb_request_is_done(struct ldb_request *req);
805
806 int ldb_modules_wait(struct ldb_handle *handle);
807 int ldb_wait(struct ldb_handle *handle, enum ldb_wait_type type);
808
809 int ldb_set_timeout(struct ldb_context *ldb, struct ldb_request *req, int timeout);
810 int ldb_set_timeout_from_prev_req(struct ldb_context *ldb, struct ldb_request *oldreq, struct ldb_request *newreq);
811 void ldb_set_create_perms(struct ldb_context *ldb, unsigned int perms);
812 void ldb_set_modules_dir(struct ldb_context *ldb, const char *path);
813 struct tevent_context;
814 void ldb_set_event_context(struct ldb_context *ldb, struct tevent_context *ev);
815 struct tevent_context * ldb_get_event_context(struct ldb_context *ldb);
816
817 /**
818   Initialise ldbs' global information
819
820   This is required before any other LDB call
821
822   \return 0 if initialisation succeeded, -1 otherwise
823 */
824 int ldb_global_init(void);
825
826 /**
827   Initialise an ldb context
828
829   This is required before any other LDB call.
830
831   \param mem_ctx pointer to a talloc memory context. Pass NULL if there is
832   no suitable context available.
833
834   \return pointer to ldb_context that should be free'd (using talloc_free())
835   at the end of the program.
836 */
837 struct ldb_context *ldb_init(TALLOC_CTX *mem_ctx, struct tevent_context *ev_ctx);
838
839 /**
840    Connect to a database.
841
842    This is typically called soon after ldb_init(), and is required prior to
843    any search or database modification operations.
844
845    The URL can be one of the following forms:
846     - tdb://path
847     - ldapi://path
848     - ldap://host
849     - sqlite://path
850
851    \param ldb the context associated with the database (from ldb_init())
852    \param url the URL of the database to connect to, as noted above
853    \param flags a combination of LDB_FLG_* to modify the connection behaviour
854    \param options backend specific options - passed uninterpreted to the backend
855
856    \return result code (LDB_SUCCESS on success, or a failure code)
857
858    \note It is an error to connect to a database that does not exist in readonly mode
859    (that is, with LDB_FLG_RDONLY). However in read-write mode, the database will be
860    created if it does not exist.
861 */
862
863 typedef void (*ldb_async_timeout_fn) (void *);
864 typedef bool (*ldb_async_callback_fn) (void *);
865 typedef int (*ldb_async_ctx_add_op_fn)(void *, time_t, void *, ldb_async_timeout_fn, ldb_async_callback_fn);
866 typedef int (*ldb_async_ctx_wait_op_fn)(void *);
867
868 void ldb_async_ctx_set_private_data(struct ldb_context *ldb,
869                                         void *private_data);
870 void ldb_async_ctx_set_add_op(struct ldb_context *ldb,
871                                 ldb_async_ctx_add_op_fn add_op);
872 void ldb_async_ctx_set_wait_op(struct ldb_context *ldb,
873                                 ldb_async_ctx_wait_op_fn wait_op);
874
875 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
876
877 /*
878   return an automatic basedn from the rootDomainNamingContext of the rootDSE
879   This value have been set in an opaque pointer at connection time
880 */
881 struct ldb_dn *ldb_get_root_basedn(struct ldb_context *ldb);
882
883 /*
884   return an automatic basedn from the configurationNamingContext of the rootDSE
885   This value have been set in an opaque pointer at connection time
886 */
887 struct ldb_dn *ldb_get_config_basedn(struct ldb_context *ldb);
888
889 /*
890   return an automatic basedn from the schemaNamingContext of the rootDSE
891   This value have been set in an opaque pointer at connection time
892 */
893 struct ldb_dn *ldb_get_schema_basedn(struct ldb_context *ldb);
894
895 /*
896   return an automatic baseDN from the defaultNamingContext of the rootDSE
897   This value have been set in an opaque pointer at connection time
898 */
899 struct ldb_dn *ldb_get_default_basedn(struct ldb_context *ldb);
900
901 /**
902   The default async search callback function 
903
904   \param req the request we are callback of
905   \param ares a single reply from the async core
906
907   \return result code (LDB_SUCCESS on success, or a failure code)
908
909   \note this function expects req->context to always be an struct ldb_result pointer
910   AND a talloc context, this function will steal on the context each message
911   from the ares reply passed on by the async core so that in the end all the
912   messages will be in the context (ldb_result)  memory tree.
913   Freeing the passed context (ldb_result tree) will free all the resources
914   (the request need to be freed separately and the result doe not depend on the
915   request that can be freed as sson as the search request is finished)
916 */
917
918 int ldb_search_default_callback(struct ldb_request *req, struct ldb_reply *ares);
919
920 /**
921   The default async extended operation callback function
922
923   \param req the request we are callback of
924   \param ares a single reply from the async core
925
926   \return result code (LDB_SUCCESS on success, or a failure code)
927 */
928 int ldb_op_default_callback(struct ldb_request *req, struct ldb_reply *ares);
929
930
931 /**
932   Helper function to build a search request
933
934   \param ret_req the request structure is returned here (talloced on mem_ctx)
935   \param ldb the context associated with the database (from ldb_init())
936   \param mem_ctx a talloc memory context (used as parent of ret_req)
937   \param base the Base Distinguished Name for the query (use ldb_dn_new() for an empty one)
938   \param scope the search scope for the query
939   \param expression the search expression to use for this query
940   \param attrs the search attributes for the query (pass NULL if none required)
941   \param controls an array of controls
942   \param context the callback function context
943   \param the callback function to handle the async replies
944   \param the parent request if any
945
946   \return result code (LDB_SUCCESS on success, or a failure code)
947 */
948
949 int ldb_build_search_req(struct ldb_request **ret_req,
950                         struct ldb_context *ldb,
951                         TALLOC_CTX *mem_ctx,
952                         struct ldb_dn *base,
953                         enum ldb_scope scope,
954                         const char *expression,
955                         const char * const *attrs,
956                         struct ldb_control **controls,
957                         void *context,
958                         ldb_request_callback_t callback,
959                         struct ldb_request *parent);
960
961 int ldb_build_search_req_ex(struct ldb_request **ret_req,
962                         struct ldb_context *ldb,
963                         TALLOC_CTX *mem_ctx,
964                         struct ldb_dn *base,
965                         enum ldb_scope scope,
966                         struct ldb_parse_tree *tree,
967                         const char * const *attrs,
968                         struct ldb_control **controls,
969                         void *context,
970                         ldb_request_callback_t callback,
971                         struct ldb_request *parent);
972
973 /**
974   Helper function to build an add request
975
976   \param ret_req the request structure is returned here (talloced on mem_ctx)
977   \param ldb the context associated with the database (from ldb_init())
978   \param mem_ctx a talloc memory context (used as parent of ret_req)
979   \param message contains the entry to be added 
980   \param controls an array of controls
981   \param context the callback function context
982   \param the callback function to handle the async replies
983   \param the parent request if any
984
985   \return result code (LDB_SUCCESS on success, or a failure code)
986 */
987
988 int ldb_build_add_req(struct ldb_request **ret_req,
989                         struct ldb_context *ldb,
990                         TALLOC_CTX *mem_ctx,
991                         const struct ldb_message *message,
992                         struct ldb_control **controls,
993                         void *context,
994                         ldb_request_callback_t callback,
995                         struct ldb_request *parent);
996
997 /**
998   Helper function to build a modify request
999
1000   \param ret_req the request structure is returned here (talloced on mem_ctx)
1001   \param ldb the context associated with the database (from ldb_init())
1002   \param mem_ctx a talloc memory context (used as parent of ret_req)
1003   \param message contains the entry to be modified
1004   \param controls an array of controls
1005   \param context the callback function context
1006   \param the callback function to handle the async replies
1007   \param the parent request if any
1008
1009   \return result code (LDB_SUCCESS on success, or a failure code)
1010 */
1011
1012 int ldb_build_mod_req(struct ldb_request **ret_req,
1013                         struct ldb_context *ldb,
1014                         TALLOC_CTX *mem_ctx,
1015                         const struct ldb_message *message,
1016                         struct ldb_control **controls,
1017                         void *context,
1018                         ldb_request_callback_t callback,
1019                         struct ldb_request *parent);
1020
1021 /**
1022   Helper function to build a delete request
1023
1024   \param ret_req the request structure is returned here (talloced on mem_ctx)
1025   \param ldb the context associated with the database (from ldb_init())
1026   \param mem_ctx a talloc memory context (used as parent of ret_req)
1027   \param dn the DN to be deleted
1028   \param controls an array of controls
1029   \param context the callback function context
1030   \param the callback function to handle the async replies
1031   \param the parent request if any
1032
1033   \return result code (LDB_SUCCESS on success, or a failure code)
1034 */
1035
1036 int ldb_build_del_req(struct ldb_request **ret_req,
1037                         struct ldb_context *ldb,
1038                         TALLOC_CTX *mem_ctx,
1039                         struct ldb_dn *dn,
1040                         struct ldb_control **controls,
1041                         void *context,
1042                         ldb_request_callback_t callback,
1043                         struct ldb_request *parent);
1044
1045 /**
1046   Helper function to build a rename request
1047
1048   \param ret_req the request structure is returned here (talloced on mem_ctx)
1049   \param ldb the context associated with the database (from ldb_init())
1050   \param mem_ctx a talloc memory context (used as parent of ret_req)
1051   \param olddn the old DN
1052   \param newdn the new DN
1053   \param controls an array of controls
1054   \param context the callback function context
1055   \param the callback function to handle the async replies
1056   \param the parent request if any
1057
1058   \return result code (LDB_SUCCESS on success, or a failure code)
1059 */
1060
1061 int ldb_build_rename_req(struct ldb_request **ret_req,
1062                         struct ldb_context *ldb,
1063                         TALLOC_CTX *mem_ctx,
1064                         struct ldb_dn *olddn,
1065                         struct ldb_dn *newdn,
1066                         struct ldb_control **controls,
1067                         void *context,
1068                         ldb_request_callback_t callback,
1069                         struct ldb_request *parent);
1070
1071 /**
1072   Add a ldb_control to a ldb_request
1073
1074   \param req the request struct where to add the control
1075   \param oid the object identifier of the control as string
1076   \param critical whether the control should be critical or not
1077   \param data a talloc pointer to the control specific data
1078
1079   \return result code (LDB_SUCCESS on success, or a failure code)
1080 */
1081 int ldb_request_add_control(struct ldb_request *req, const char *oid, bool critical, void *data);
1082
1083 /**
1084    check if a control with the specified "oid" exist and return it 
1085   \param req the request struct where to add the control
1086   \param oid the object identifier of the control as string
1087
1088   \return the control, NULL if not found 
1089 */
1090 struct ldb_control *ldb_request_get_control(struct ldb_request *req, const char *oid);
1091
1092 /**
1093    check if a control with the specified "oid" exist and return it 
1094   \param rep the reply struct where to add the control
1095   \param oid the object identifier of the control as string
1096
1097   \return the control, NULL if not found 
1098 */
1099 struct ldb_control *ldb_reply_get_control(struct ldb_reply *rep, const char *oid);
1100
1101 /**
1102   Search the database
1103
1104   This function searches the database, and returns 
1105   records that match an LDAP-like search expression
1106
1107   \param ldb the context associated with the database (from ldb_init())
1108   \param mem_ctx the memory context to use for the request and the results
1109   \param result the return result
1110   \param base the Base Distinguished Name for the query (use ldb_dn_new() for an empty one)
1111   \param scope the search scope for the query
1112   \param attrs the search attributes for the query (pass NULL if none required)
1113   \param exp_fmt the search expression to use for this query (printf like)
1114
1115   \return result code (LDB_SUCCESS on success, or a failure code)
1116
1117   \note use talloc_free() to free the ldb_result returned
1118 */
1119 int ldb_search(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
1120                struct ldb_result **result, struct ldb_dn *base,
1121                enum ldb_scope scope, const char * const *attrs,
1122                const char *exp_fmt, ...) PRINTF_ATTRIBUTE(7,8);
1123
1124 /**
1125   Add a record to the database.
1126
1127   This function adds a record to the database. This function will fail
1128   if a record with the specified class and key already exists in the
1129   database. 
1130
1131   \param ldb the context associated with the database (from
1132   ldb_init())
1133   \param message the message containing the record to add.
1134
1135   \return result code (LDB_SUCCESS if the record was added, otherwise
1136   a failure code)
1137 */
1138 int ldb_add(struct ldb_context *ldb, 
1139             const struct ldb_message *message);
1140
1141 /**
1142   Modify the specified attributes of a record
1143
1144   This function modifies a record that is in the database.
1145
1146   \param ldb the context associated with the database (from
1147   ldb_init())
1148   \param message the message containing the changes required.
1149
1150   \return result code (LDB_SUCCESS if the record was modified as
1151   requested, otherwise a failure code)
1152 */
1153 int ldb_modify(struct ldb_context *ldb, 
1154                const struct ldb_message *message);
1155
1156 /**
1157   Rename a record in the database
1158
1159   This function renames a record in the database.
1160
1161   \param ldb the context associated with the database (from
1162   ldb_init())
1163   \param olddn the DN for the record to be renamed.
1164   \param newdn the new DN 
1165
1166   \return result code (LDB_SUCCESS if the record was renamed as
1167   requested, otherwise a failure code)
1168 */
1169 int ldb_rename(struct ldb_context *ldb, struct ldb_dn *olddn, struct ldb_dn *newdn);
1170
1171 /**
1172   Delete a record from the database
1173
1174   This function deletes a record from the database.
1175
1176   \param ldb the context associated with the database (from
1177   ldb_init())
1178   \param dn the DN for the record to be deleted.
1179
1180   \return result code (LDB_SUCCESS if the record was deleted,
1181   otherwise a failure code)
1182 */
1183 int ldb_delete(struct ldb_context *ldb, struct ldb_dn *dn);
1184
1185 /**
1186   The default async extended operation callback function 
1187
1188   \param req the request we are callback of
1189   \param ares a single reply from the async core
1190
1191   \return result code (LDB_SUCCESS on success, or a failure code)
1192
1193   \note this function expects req->context to always be an struct ldb_result pointer
1194   AND a talloc context, this function will steal on the context each message
1195   from the ares reply passed on by the async core so that in the end all the
1196   messages will be in the context (ldb_result)  memory tree.
1197   Freeing the passed context (ldb_result tree) will free all the resources
1198   (the request need to be freed separately and the result doe not depend on the
1199   request that can be freed as sson as the search request is finished)
1200 */
1201
1202 int ldb_extended_default_callback(struct ldb_request *req, struct ldb_reply *ares);
1203
1204
1205 /**
1206   Helper function to build a extended request
1207
1208   \param ret_req the request structure is returned here (talloced on mem_ctx)
1209   \param ldb the context associated with the database (from ldb_init())
1210   \param mem_ctx a talloc memory context (used as parent of ret_req)
1211   \param oid the OID of the extended operation.
1212   \param data a void pointer a the extended operation specific parameters,
1213   it needs to be NULL or a valid talloc pointer! talloc_get_type() will be used on it  
1214   \param controls an array of controls
1215   \param context the callback function context
1216   \param the callback function to handle the async replies
1217   \param the parent request if any
1218
1219   \return result code (LDB_SUCCESS on success, or a failure code)
1220 */
1221 int ldb_build_extended_req(struct ldb_request **ret_req,
1222                            struct ldb_context *ldb,
1223                            TALLOC_CTX *mem_ctx,
1224                            const char *oid,
1225                            void *data,/* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
1226                            struct ldb_control **controls,
1227                            void *context,
1228                            ldb_request_callback_t callback,
1229                            struct ldb_request *parent);
1230
1231 /**
1232   call an extended operation
1233
1234   This function deletes a record from the database.
1235
1236   \param ldb the context associated with the database (from ldb_init())
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 res the result of the extended operation
1241
1242   \return result code (LDB_SUCCESS if the extended operation returned fine,
1243   otherwise a failure code)
1244 */
1245 int ldb_extended(struct ldb_context *ldb, 
1246                  const char *oid,
1247                  void *data,/* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
1248                  struct ldb_result **res);
1249
1250 /**
1251   Obtain current/next database sequence number
1252 */
1253 int ldb_sequence_number(struct ldb_context *ldb, enum ldb_sequence_type type, uint64_t *seq_num);
1254
1255 /**
1256   start a transaction
1257 */
1258 int ldb_transaction_start(struct ldb_context *ldb);
1259
1260 /**
1261   commit a transaction
1262 */
1263 int ldb_transaction_commit(struct ldb_context *ldb);
1264
1265 /**
1266   cancel a transaction
1267 */
1268 int ldb_transaction_cancel(struct ldb_context *ldb);
1269
1270
1271 /**
1272   return extended error information from the last call
1273 */
1274 const char *ldb_errstring(struct ldb_context *ldb);
1275
1276 /**
1277   return a string explaining what a ldb error constant meancs
1278 */
1279 const char *ldb_strerror(int ldb_err);
1280
1281 /**
1282   setup the default utf8 functions
1283   FIXME: these functions do not yet handle utf8
1284 */
1285 void ldb_set_utf8_default(struct ldb_context *ldb);
1286
1287 /**
1288    Casefold a string
1289
1290    \param ldb the ldb context
1291    \param mem_ctx the memory context to allocate the result string
1292    memory from. 
1293    \param s the string that is to be folded
1294    \return a copy of the string, converted to upper case
1295
1296    \note The default function is not yet UTF8 aware. Provide your own
1297          set of functions through ldb_set_utf8_fns()
1298 */
1299 char *ldb_casefold(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *s, size_t n);
1300
1301 /**
1302    Check the attribute name is valid according to rfc2251
1303    \param s the string to check
1304
1305    \return 1 if the name is ok
1306 */
1307 int ldb_valid_attr_name(const char *s);
1308
1309 /*
1310   ldif manipulation functions
1311 */
1312
1313 /**
1314    Write an LDIF message
1315
1316    This function writes an LDIF message using a caller supplied  write
1317    function.
1318
1319    \param ldb the ldb context (from ldb_init())
1320    \param fprintf_fn a function pointer for the write function. This must take
1321    a private data pointer, followed by a format string, and then a variable argument
1322    list. 
1323    \param private_data pointer that will be provided back to the write
1324    function. This is useful for maintaining state or context.
1325    \param ldif the message to write out
1326
1327    \return the total number of bytes written, or an error code as returned
1328    from the write function.
1329
1330    \sa ldb_ldif_write_file for a more convenient way to write to a
1331    file stream.
1332
1333    \sa ldb_ldif_read for the reader equivalent to this function.
1334 */
1335 int ldb_ldif_write(struct ldb_context *ldb,
1336                    int (*fprintf_fn)(void *, const char *, ...) PRINTF_ATTRIBUTE(2,3), 
1337                    void *private_data,
1338                    const struct ldb_ldif *ldif);
1339
1340 /**
1341    Clean up an LDIF message
1342
1343    This function cleans up a LDIF message read using ldb_ldif_read()
1344    or related functions (such as ldb_ldif_read_string() and
1345    ldb_ldif_read_file().
1346
1347    \param ldb the ldb context (from ldb_init())
1348    \param msg the message to clean up and free
1349
1350 */
1351 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *msg);
1352
1353 /**
1354    Read an LDIF message
1355
1356    This function creates an LDIF message using a caller supplied read
1357    function. 
1358
1359    \param ldb the ldb context (from ldb_init())
1360    \param fgetc_fn a function pointer for the read function. This must
1361    take a private data pointer, and must return a pointer to an
1362    integer corresponding to the next byte read (or EOF if there is no
1363    more data to be read).
1364    \param private_data pointer that will be provided back to the read
1365    function. This is udeful for maintaining state or context.
1366
1367    \return the LDIF message that has been read in
1368
1369    \note You must free the LDIF message when no longer required, using
1370    ldb_ldif_read_free().
1371
1372    \sa ldb_ldif_read_file for a more convenient way to read from a
1373    file stream.
1374
1375    \sa ldb_ldif_read_string for a more convenient way to read from a
1376    string (char array).
1377
1378    \sa ldb_ldif_write for the writer equivalent to this function.
1379 */
1380 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb, 
1381                                int (*fgetc_fn)(void *), void *private_data);
1382
1383 /**
1384    Read an LDIF message from a file
1385
1386    This function reads the next LDIF message from the contents of a
1387    file stream. If you want to get all of the LDIF messages, you will
1388    need to repeatedly call this function, until it returns NULL.
1389
1390    \param ldb the ldb context (from ldb_init())
1391    \param f the file stream to read from (typically from fdopen())
1392
1393    \sa ldb_ldif_read_string for an equivalent function that will read
1394    from a string (char array).
1395
1396    \sa ldb_ldif_write_file for the writer equivalent to this function.
1397
1398 */
1399 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
1400
1401 /**
1402    Read an LDIF message from a string
1403
1404    This function reads the next LDIF message from the contents of a char
1405    array. If you want to get all of the LDIF messages, you will need
1406    to repeatedly call this function, until it returns NULL.
1407
1408    \param ldb the ldb context (from ldb_init())
1409    \param s pointer to the char array to read from
1410
1411    \sa ldb_ldif_read_file for an equivalent function that will read
1412    from a file stream.
1413
1414    \sa ldb_ldif_write for a more general (arbitrary read function)
1415    version of this function.
1416 */
1417 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
1418
1419 /**
1420    Write an LDIF message to a file
1421
1422    \param ldb the ldb context (from ldb_init())
1423    \param f the file stream to write to (typically from fdopen())
1424    \param msg the message to write out
1425
1426    \return the total number of bytes written, or a negative error code
1427
1428    \sa ldb_ldif_read_file for the reader equivalent to this function.
1429 */
1430 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
1431
1432 /**
1433    Base64 encode a buffer
1434
1435    \param mem_ctx the memory context that the result is allocated
1436    from. 
1437    \param buf pointer to the array that is to be encoded
1438    \param len the number of elements in the array to be encoded
1439
1440    \return pointer to an array containing the encoded data
1441
1442    \note The caller is responsible for freeing the result
1443 */
1444 char *ldb_base64_encode(TALLOC_CTX *mem_ctx, const char *buf, int len);
1445
1446 /**
1447    Base64 decode a buffer
1448
1449    This function decodes a base64 encoded string in place.
1450
1451    \param s the string to decode.
1452
1453    \return the length of the returned (decoded) string.
1454
1455    \note the string is null terminated, but the null terminator is not
1456    included in the length.
1457 */
1458 int ldb_base64_decode(char *s);
1459
1460 /* The following definitions come from lib/ldb/common/ldb_dn.c  */
1461
1462 /**
1463   Get the linear form of a DN (without any extended components)
1464   
1465   \param dn The DN to linearize
1466 */
1467
1468 const char *ldb_dn_get_linearized(struct ldb_dn *dn);
1469
1470 /**
1471   Allocate a copy of the linear form of a DN (without any extended components) onto the supplied memory context 
1472   
1473   \param dn The DN to linearize
1474   \param mem_ctx TALLOC context to return result on
1475 */
1476
1477 char *ldb_dn_alloc_linearized(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1478
1479 /**
1480   Get the linear form of a DN (with any extended components)
1481   
1482   \param mem_ctx TALLOC context to return result on
1483   \param dn The DN to linearize
1484   \param mode Style of extended DN to return (0 is HEX representation of binary form, 1 is a string form)
1485 */
1486 char *ldb_dn_get_extended_linearized(void *mem_ctx, struct ldb_dn *dn, int mode);
1487 const struct ldb_val *ldb_dn_get_extended_component(struct ldb_dn *dn, const char *name);
1488 int ldb_dn_set_extended_component(struct ldb_dn *dn, const char *name, const struct ldb_val *val);
1489
1490 void ldb_dn_remove_extended_components(struct ldb_dn *dn);
1491 bool ldb_dn_has_extended(struct ldb_dn *dn);
1492
1493 int ldb_dn_extended_add_syntax(struct ldb_context *ldb, 
1494                                unsigned flags,
1495                                const struct ldb_dn_extended_syntax *syntax);
1496
1497 /** 
1498   Allocate a new DN from a string
1499
1500   \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1501   \param dn The new DN 
1502
1503   \note The DN will not be parsed at this time.  Use ldb_dn_validate to tell if the DN is syntacticly correct
1504 */
1505
1506 struct ldb_dn *ldb_dn_new(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *dn);
1507 /** 
1508   Allocate a new DN from a printf style format string and arguments
1509
1510   \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1511   \param new_fms The new DN as a format string (plus arguments)
1512
1513   \note The DN will not be parsed at this time.  Use ldb_dn_validate to tell if the DN is syntacticly correct
1514 */
1515
1516 struct ldb_dn *ldb_dn_new_fmt(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *new_fmt, ...) PRINTF_ATTRIBUTE(3,4);
1517 /** 
1518   Allocate a new DN from a struct ldb_val (useful to avoid buffer overrun)
1519
1520   \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1521   \param dn The new DN 
1522
1523   \note The DN will not be parsed at this time.  Use ldb_dn_validate to tell if the DN is syntacticly correct
1524 */
1525
1526 struct ldb_dn *ldb_dn_from_ldb_val(void *mem_ctx, struct ldb_context *ldb, const struct ldb_val *strdn);
1527
1528 /**
1529   Determine if this DN is syntactically valid 
1530
1531   \param dn The DN to validate
1532 */
1533
1534 bool ldb_dn_validate(struct ldb_dn *dn);
1535
1536 char *ldb_dn_escape_value(TALLOC_CTX *mem_ctx, struct ldb_val value);
1537 const char *ldb_dn_get_casefold(struct ldb_dn *dn);
1538 char *ldb_dn_alloc_casefold(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1539
1540 int ldb_dn_compare_base(struct ldb_dn *base, struct ldb_dn *dn);
1541 int ldb_dn_compare(struct ldb_dn *edn0, struct ldb_dn *edn1);
1542
1543 bool ldb_dn_add_base(struct ldb_dn *dn, struct ldb_dn *base);
1544 bool ldb_dn_add_base_fmt(struct ldb_dn *dn, const char *base_fmt, ...) PRINTF_ATTRIBUTE(2,3);
1545 bool ldb_dn_add_child(struct ldb_dn *dn, struct ldb_dn *child);
1546 bool ldb_dn_add_child_fmt(struct ldb_dn *dn, const char *child_fmt, ...) PRINTF_ATTRIBUTE(2,3);
1547 bool ldb_dn_remove_base_components(struct ldb_dn *dn, unsigned int num);
1548 bool ldb_dn_remove_child_components(struct ldb_dn *dn, unsigned int num);
1549
1550 struct ldb_dn *ldb_dn_copy(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1551 struct ldb_dn *ldb_dn_get_parent(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1552 char *ldb_dn_canonical_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1553 char *ldb_dn_canonical_ex_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1554 int ldb_dn_get_comp_num(struct ldb_dn *dn);
1555 const char *ldb_dn_get_component_name(struct ldb_dn *dn, unsigned int num);
1556 const struct ldb_val *ldb_dn_get_component_val(struct ldb_dn *dn, unsigned int num);
1557 const char *ldb_dn_get_rdn_name(struct ldb_dn *dn);
1558 const struct ldb_val *ldb_dn_get_rdn_val(struct ldb_dn *dn);
1559 int ldb_dn_set_component(struct ldb_dn *dn, int num, const char *name, const struct ldb_val val);
1560
1561 bool ldb_dn_is_valid(struct ldb_dn *dn);
1562 bool ldb_dn_is_special(struct ldb_dn *dn);
1563 bool ldb_dn_check_special(struct ldb_dn *dn, const char *check);
1564 bool ldb_dn_is_null(struct ldb_dn *dn);
1565
1566
1567 /**
1568    Compare two attributes
1569
1570    This function compares to attribute names. Note that this is a
1571    case-insensitive comparison.
1572
1573    \param a the first attribute name to compare
1574    \param b the second attribute name to compare
1575
1576    \return 0 if the attribute names are the same, or only differ in
1577    case; non-zero if there are any differences
1578
1579   attribute names are restricted by rfc2251 so using
1580   strcasecmp and toupper here is ok.
1581   return 0 for match
1582 */
1583 #define ldb_attr_cmp(a, b) strcasecmp(a, b)
1584 char *ldb_attr_casefold(TALLOC_CTX *mem_ctx, const char *s);
1585 int ldb_attr_dn(const char *attr);
1586
1587 /**
1588    Create an empty message
1589
1590    \param mem_ctx the memory context to create in. You can pass NULL
1591    to get the top level context, however the ldb context (from
1592    ldb_init()) may be a better choice
1593 */
1594 struct ldb_message *ldb_msg_new(TALLOC_CTX *mem_ctx);
1595
1596 /**
1597    Find an element within an message
1598 */
1599 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg, 
1600                                                  const char *attr_name);
1601
1602 /**
1603    Compare two ldb_val values
1604
1605    \param v1 first ldb_val structure to be tested
1606    \param v2 second ldb_val structure to be tested
1607
1608    \return 1 for a match, 0 if there is any difference
1609 */
1610 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
1611
1612 /**
1613    find a value within an ldb_message_element
1614
1615    \param el the element to search
1616    \param val the value to search for
1617
1618    \note This search is case sensitive
1619 */
1620 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el, 
1621                                  struct ldb_val *val);
1622
1623 /**
1624    add a new empty element to a ldb_message
1625 */
1626 int ldb_msg_add_empty(struct ldb_message *msg,
1627                 const char *attr_name,
1628                 int flags,
1629                 struct ldb_message_element **return_el);
1630
1631 /**
1632    add a element to a ldb_message
1633 */
1634 int ldb_msg_add(struct ldb_message *msg, 
1635                 const struct ldb_message_element *el, 
1636                 int flags);
1637 int ldb_msg_add_value(struct ldb_message *msg, 
1638                 const char *attr_name,
1639                 const struct ldb_val *val,
1640                 struct ldb_message_element **return_el);
1641 int ldb_msg_add_steal_value(struct ldb_message *msg, 
1642                       const char *attr_name,
1643                       struct ldb_val *val);
1644 int ldb_msg_add_steal_string(struct ldb_message *msg, 
1645                              const char *attr_name, char *str);
1646 int ldb_msg_add_string(struct ldb_message *msg, 
1647                        const char *attr_name, const char *str);
1648 int ldb_msg_add_fmt(struct ldb_message *msg, 
1649                     const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
1650
1651 /**
1652    compare two message elements - return 0 on match
1653 */
1654 int ldb_msg_element_compare(struct ldb_message_element *el1, 
1655                             struct ldb_message_element *el2);
1656 int ldb_msg_element_compare_name(struct ldb_message_element *el1, 
1657                                  struct ldb_message_element *el2);
1658
1659 /**
1660    Find elements in a message.
1661
1662    This function finds elements and converts to a specific type, with
1663    a give default value if not found. Assumes that elements are
1664    single valued.
1665 */
1666 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
1667 int ldb_msg_find_attr_as_int(const struct ldb_message *msg, 
1668                              const char *attr_name,
1669                              int default_value);
1670 unsigned int ldb_msg_find_attr_as_uint(const struct ldb_message *msg, 
1671                                        const char *attr_name,
1672                                        unsigned int default_value);
1673 int64_t ldb_msg_find_attr_as_int64(const struct ldb_message *msg, 
1674                                    const char *attr_name,
1675                                    int64_t default_value);
1676 uint64_t ldb_msg_find_attr_as_uint64(const struct ldb_message *msg, 
1677                                      const char *attr_name,
1678                                      uint64_t default_value);
1679 double ldb_msg_find_attr_as_double(const struct ldb_message *msg, 
1680                                    const char *attr_name,
1681                                    double default_value);
1682 int ldb_msg_find_attr_as_bool(const struct ldb_message *msg, 
1683                               const char *attr_name,
1684                               int default_value);
1685 const char *ldb_msg_find_attr_as_string(const struct ldb_message *msg, 
1686                                         const char *attr_name,
1687                                         const char *default_value);
1688
1689 struct ldb_dn *ldb_msg_find_attr_as_dn(struct ldb_context *ldb,
1690                                        TALLOC_CTX *mem_ctx,
1691                                        const struct ldb_message *msg,
1692                                        const char *attr_name);
1693
1694 void ldb_msg_sort_elements(struct ldb_message *msg);
1695
1696 struct ldb_message *ldb_msg_copy_shallow(TALLOC_CTX *mem_ctx, 
1697                                          const struct ldb_message *msg);
1698 struct ldb_message *ldb_msg_copy(TALLOC_CTX *mem_ctx, 
1699                                  const struct ldb_message *msg);
1700
1701 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb, 
1702                                          const struct ldb_message *msg);
1703
1704
1705 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb, 
1706                                  struct ldb_message *msg1,
1707                                  struct ldb_message *msg2);
1708
1709 int ldb_msg_check_string_attribute(const struct ldb_message *msg,
1710                                    const char *name,
1711                                    const char *value);
1712
1713 /**
1714    Integrity check an ldb_message
1715
1716    This function performs basic sanity / integrity checks on an
1717    ldb_message.
1718
1719    \param ldb context in which to perform the checks
1720    \param msg the message to check
1721
1722    \return LDB_SUCCESS if the message is OK, or a non-zero error code
1723    (one of LDB_ERR_INVALID_DN_SYNTAX, LDB_ERR_ENTRY_ALREADY_EXISTS or
1724    LDB_ERR_INVALID_ATTRIBUTE_SYNTAX) if there is a problem with a
1725    message.
1726 */
1727 int ldb_msg_sanity_check(struct ldb_context *ldb,
1728                          const struct ldb_message *msg);
1729
1730 /**
1731    Duplicate an ldb_val structure
1732
1733    This function copies an ldb value structure. 
1734
1735    \param mem_ctx the memory context that the duplicated value will be
1736    allocated from
1737    \param v the ldb_val to be duplicated.
1738
1739    \return the duplicated ldb_val structure.
1740 */
1741 struct ldb_val ldb_val_dup(TALLOC_CTX *mem_ctx, const struct ldb_val *v);
1742
1743 /**
1744   this allows the user to set a debug function for error reporting
1745 */
1746 int ldb_set_debug(struct ldb_context *ldb,
1747                   void (*debug)(void *context, enum ldb_debug_level level, 
1748                                 const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0),
1749                   void *context);
1750
1751 /**
1752   this allows the user to set custom utf8 function for error reporting
1753 */
1754 void ldb_set_utf8_fns(struct ldb_context *ldb,
1755                       void *context,
1756                       char *(*casefold)(void *, void *, const char *, size_t n));
1757
1758 /**
1759    this sets up debug to print messages on stderr
1760 */
1761 int ldb_set_debug_stderr(struct ldb_context *ldb);
1762
1763 /* control backend specific opaque values */
1764 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
1765 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
1766
1767 const char **ldb_attr_list_copy(TALLOC_CTX *mem_ctx, const char * const *attrs);
1768 const char **ldb_attr_list_copy_add(TALLOC_CTX *mem_ctx, const char * const *attrs, const char *new_attr);
1769 int ldb_attr_in_list(const char * const *attrs, const char *attr);
1770
1771 int ldb_msg_rename_attr(struct ldb_message *msg, const char *attr, const char *replace);
1772 int ldb_msg_copy_attr(struct ldb_message *msg, const char *attr, const char *replace);
1773 void ldb_msg_remove_attr(struct ldb_message *msg, const char *attr);
1774 void ldb_msg_remove_element(struct ldb_message *msg, struct ldb_message_element *el);
1775
1776
1777 void ldb_parse_tree_attr_replace(struct ldb_parse_tree *tree, 
1778                                  const char *attr, 
1779                                  const char *replace);
1780
1781
1782 /**
1783    Convert a time structure to a string
1784
1785    This function converts a time_t structure to an LDAP formatted
1786    GeneralizedTime string.
1787                 
1788    \param mem_ctx the memory context to allocate the return string in
1789    \param t the time structure to convert
1790
1791    \return the formatted string, or NULL if the time structure could
1792    not be converted
1793 */
1794 char *ldb_timestring(TALLOC_CTX *mem_ctx, time_t t);
1795
1796 /**
1797    Convert a string to a time structure
1798
1799    This function converts an LDAP formatted GeneralizedTime string
1800    to a time_t structure.
1801
1802    \param s the string to convert
1803
1804    \return the time structure, or 0 if the string cannot be converted
1805 */
1806 time_t ldb_string_to_time(const char *s);
1807
1808 /**
1809    Convert a time structure to a string
1810
1811    This function converts a time_t structure to an LDAP formatted
1812    UTCTime string.
1813                 
1814    \param mem_ctx the memory context to allocate the return string in
1815    \param t the time structure to convert
1816
1817    \return the formatted string, or NULL if the time structure could
1818    not be converted
1819 */
1820 char *ldb_timestring_utc(TALLOC_CTX *mem_ctx, time_t t);
1821
1822 /**
1823    Convert a string to a time structure
1824
1825    This function converts an LDAP formatted UTCTime string
1826    to a time_t structure.
1827
1828    \param s the string to convert
1829
1830    \return the time structure, or 0 if the string cannot be converted
1831 */
1832 time_t ldb_string_utc_to_time(const char *s);
1833
1834
1835 void ldb_qsort (void *const pbase, size_t total_elems, size_t size, void *opaque, ldb_qsort_cmp_fn_t cmp);
1836
1837
1838 /**
1839    Convert an array of string represention of a control into an array of ldb_control structures 
1840    
1841    \param ldb LDB context
1842    \param mem_ctx TALLOC context to return result on, and to allocate error_string on
1843    \param control_strings Array of string-formatted controls
1844
1845    \return array of ldb_control elements
1846 */
1847 struct ldb_control **ldb_parse_control_strings(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char **control_strings);
1848
1849 #endif