r13324: From now on check attribute names obey rfc2251
[samba.git] / source / 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
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 2 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, write to the Free Software
24    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
25 */
26
27 /*
28  *  Name: ldb
29  *
30  *  Component: ldb header
31  *
32  *  Description: defines for base ldb API
33  *
34  *  Author: Andrew Tridgell
35  *  Author: Stefan Metzmacher
36  */
37
38 /**
39    \file ldb.h Samba's ldb database
40
41    This header file provides the main API for ldb.
42 */
43
44 #ifndef _LDB_H_
45
46 /*! \cond DOXYGEN_IGNORE */
47 #define _LDB_H_ 1
48 /*! \endcond */
49
50 /*
51   major restrictions as compared to normal LDAP:
52
53      - no async calls.
54      - each record must have a unique key field
55      - the key must be representable as a NULL terminated C string and may not 
56        contain a comma or braces
57
58   major restrictions as compared to tdb:
59
60      - no explicit locking calls
61      UPDATE: we have transactions now, better than locking --SSS.
62
63 */
64
65 #ifndef ldb_val
66 /**
67    Result value
68
69    An individual lump of data in a result comes in this format. The
70    pointer will usually be to a UTF-8 string if the application is
71    sensible, but it can be to anything you like, including binary data
72    blobs of arbitrary size.
73
74    \note the data is null (0x00) terminated, but the length does not
75    include the terminator. 
76 */
77 struct ldb_val {
78         uint8_t *data; /*!< result data */
79         size_t length; /*!< length of data */
80 };
81 #endif
82
83 /**
84    internal ldb exploded dn structures
85 */
86 struct ldb_dn_component {
87         char *name;  
88         struct ldb_val value;
89 };
90
91 struct ldb_dn {
92         int comp_num;
93         struct ldb_dn_component *components;
94 };
95
96 /**
97  There are a number of flags that are used with ldap_modify() in
98  ldb_message_element.flags fields. The LDA_FLAGS_MOD_ADD,
99  LDA_FLAGS_MOD_DELETE and LDA_FLAGS_MOD_REPLACE flags are used in
100  ldap_modify() calls to specify whether attributes are being added,
101  deleted or modified respectively.
102 */
103 #define LDB_FLAG_MOD_MASK  0x3
104
105 /**
106    Flag value used in ldap_modify() to indicate that attributes are
107    being added.
108
109    \sa LDB_FLAG_MOD_MASK
110 */
111 #define LDB_FLAG_MOD_ADD     1
112
113 /**
114    Flag value used in ldap_modify() to indicate that attributes are
115    being replaced.
116
117    \sa LDB_FLAG_MOD_MASK
118 */
119 #define LDB_FLAG_MOD_REPLACE 2
120
121 /**
122    Flag value used in ldap_modify() to indicate that attributes are
123    being deleted.
124
125    \sa LDB_FLAG_MOD_MASK
126 */
127 #define LDB_FLAG_MOD_DELETE  3
128
129 /**
130   OID for logic AND comaprison.
131
132   This is the well known object ID for a logical AND comparitor.
133 */
134 #define LDB_OID_COMPARATOR_AND  "1.2.840.113556.1.4.803"
135
136 /**
137   OID for logic OR comparison.
138
139   This is the well known object ID for a logical OR comparitor.
140 */
141 #define LDB_OID_COMPARATOR_OR   "1.2.840.113556.1.4.804"
142
143 /**
144   results are given back as arrays of ldb_message_element
145 */
146 struct ldb_message_element {
147         unsigned int flags;
148         const char *name;
149         unsigned int num_values;
150         struct ldb_val *values;
151 };
152
153
154 /**
155   a ldb_message represents all or part of a record. It can contain an arbitrary
156   number of elements. 
157 */
158 struct ldb_message {
159         struct ldb_dn *dn;
160         unsigned int num_elements;
161         struct ldb_message_element *elements;
162         void *private_data; /* private to the backend */
163 };
164
165 enum ldb_changetype {
166         LDB_CHANGETYPE_NONE=0,
167         LDB_CHANGETYPE_ADD,
168         LDB_CHANGETYPE_DELETE,
169         LDB_CHANGETYPE_MODIFY
170 };
171
172 /**
173   LDIF record
174
175   This structure contains a LDIF record, as returned from ldif_read()
176   and equivalent functions.
177 */
178 struct ldb_ldif {
179         enum ldb_changetype changetype; /*!< The type of change */
180         struct ldb_message *msg;  /*!< The changes */
181 };
182
183 enum ldb_scope {LDB_SCOPE_DEFAULT=-1, 
184                 LDB_SCOPE_BASE=0, 
185                 LDB_SCOPE_ONELEVEL=1,
186                 LDB_SCOPE_SUBTREE=2};
187
188 struct ldb_context;
189
190 /*
191   the fuction type for the callback used in traversing the database
192 */
193 typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
194
195
196 /* debugging uses one of the following levels */
197 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR, 
198                       LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
199
200 /**
201   the user can optionally supply a debug function. The function
202   is based on the vfprintf() style of interface, but with the addition
203   of a severity level
204 */
205 struct ldb_debug_ops {
206         void (*debug)(void *context, enum ldb_debug_level level, 
207                       const char *fmt, va_list ap);
208         void *context;
209 };
210
211 /**
212   The user can optionally supply a custom utf8 functions,
213   to handle comparisons and casefolding.
214 */
215 struct ldb_utf8_fns {
216         void *context;
217         int (*caseless_cmp)(void *context, const char *s1, const char *s2);
218         char *(*casefold)(void *context, void *mem_ctx, const char *s);
219 };
220
221 /**
222    Flag value for database connection mode.
223
224    If LDB_FLG_RDONLY is used in ldb_connect, then the database will be
225    opened read-only, if possible.
226 */
227 #define LDB_FLG_RDONLY 1
228
229 /**
230    Flag value for database connection mode.
231
232    If LDB_FLG_NOSYNC is used in ldb_connect, then the database will be
233    opened without synchronous operations, if possible.
234 */
235 #define LDB_FLG_NOSYNC 2
236
237 /*! \cond DOXYGEN_IGNORE */
238 #ifndef PRINTF_ATTRIBUTE
239 #define PRINTF_ATTRIBUTE(a,b)
240 #endif
241 /*! \endcond */
242
243 /*
244    structures for ldb_parse_tree handling code
245 */
246 enum ldb_parse_op { LDB_OP_AND=1, LDB_OP_OR=2, LDB_OP_NOT=3,
247                     LDB_OP_EQUALITY=4, LDB_OP_SUBSTRING=5,
248                     LDB_OP_GREATER=6, LDB_OP_LESS=7, LDB_OP_PRESENT=8,
249                     LDB_OP_APPROX=9, LDB_OP_EXTENDED=10 };
250
251 struct ldb_parse_tree {
252         enum ldb_parse_op operation;
253         union {
254                 struct {
255                         struct ldb_parse_tree *child;
256                 } isnot;
257                 struct {
258                         const char *attr;
259                         struct ldb_val value;
260                 } equality;
261                 struct {
262                         const char *attr;
263                         int start_with_wildcard;
264                         int end_with_wildcard;
265                         struct ldb_val **chunks;
266                 } substring;
267                 struct {
268                         const char *attr;
269                 } present;
270                 struct {
271                         const char *attr;
272                         struct ldb_val value;
273                 } comparison;
274                 struct {
275                         const char *attr;
276                         int dnAttributes;
277                         char *rule_id;
278                         struct ldb_val value;
279                 } extended;
280                 struct {
281                         unsigned int num_elements;
282                         struct ldb_parse_tree **elements;
283                 } list;
284         } u;
285 };
286
287 struct ldb_parse_tree *ldb_parse_tree(void *mem_ctx, const char *s);
288 char *ldb_filter_from_tree(void *mem_ctx, struct ldb_parse_tree *tree);
289
290 /**
291    Encode a binary blob
292
293    This function encodes a binary blob using the encoding rules in RFC
294    2254 (Section 4). This function also escapes any non-printable
295    characters.
296
297    \param ctx the memory context to allocate the return string in.
298    \param val the (potentially) binary data to be encoded
299
300    \return the encoded data as a null terminated string
301
302    \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>.
303 */
304 char *ldb_binary_encode(void *ctx, struct ldb_val val);
305
306 /**
307    Encode a string
308
309    This function encodes a string using the encoding rules in RFC 2254
310    (Section 4). This function also escapes any non-printable
311    characters.
312
313    \param mem_ctx the memory context to allocate the return string in.
314    \param string the string to be encoded
315
316    \return the encoded data as a null terminated string
317
318    \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>.
319 */
320 char *ldb_binary_encode_string(void *mem_ctx, const char *string);
321
322 /*
323   functions for controlling attribute handling
324 */
325 typedef int (*ldb_attr_handler_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, struct ldb_val *);
326 typedef int (*ldb_attr_comparison_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, const struct ldb_val *);
327
328 struct ldb_attrib_handler {
329         const char *attr;
330
331         /* LDB_ATTR_FLAG_* */
332         unsigned flags;
333
334         /* convert from ldif to binary format */
335         ldb_attr_handler_t ldif_read_fn;
336
337         /* convert from binary to ldif format */
338         ldb_attr_handler_t ldif_write_fn;
339         
340         /* canonicalise a value, for use by indexing and dn construction */
341         ldb_attr_handler_t canonicalise_fn;
342
343         /* compare two values */
344         ldb_attr_comparison_t comparison_fn;
345 };
346
347 /**
348    The attribute is not returned by default
349 */
350 #define LDB_ATTR_FLAG_HIDDEN       (1<<0) 
351
352 /**
353    The attribute is constructed from other attributes
354 */
355 #define LDB_ATTR_FLAG_CONSTRUCTED  (1<<1) 
356
357 /**
358   LDAP attribute syntax for a DN
359
360   This is the well-known LDAP attribute syntax for a DN.
361
362   See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 
363 */
364 #define LDB_SYNTAX_DN                   "1.3.6.1.4.1.1466.115.121.1.12"
365
366 /**
367   LDAP attribute syntax for a Directory String
368
369   This is the well-known LDAP attribute syntax for a Directory String.
370
371   \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 
372 */
373 #define LDB_SYNTAX_DIRECTORY_STRING     "1.3.6.1.4.1.1466.115.121.1.15"
374
375 /**
376   LDAP attribute syntax for an integer
377
378   This is the well-known LDAP attribute syntax for an integer.
379
380   See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 
381 */
382 #define LDB_SYNTAX_INTEGER              "1.3.6.1.4.1.1466.115.121.1.27"
383
384 /**
385   LDAP attribute syntax for an octet string
386
387   This is the well-known LDAP attribute syntax for an octet string.
388
389   See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 
390 */
391 #define LDB_SYNTAX_OCTET_STRING         "1.3.6.1.4.1.1466.115.121.1.40"
392
393 /**
394   LDAP attribute syntax for UTC time.
395
396   This is the well-known LDAP attribute syntax for a UTC time.
397
398   See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 
399 */
400 #define LDB_SYNTAX_UTC_TIME             "1.3.6.1.4.1.1466.115.121.1.53"
401
402 #define LDB_SYNTAX_OBJECTCLASS          "LDB_SYNTAX_OBJECTCLASS"
403
404 /* sorting helpers */
405 typedef int (*ldb_qsort_cmp_fn_t) (void *v1, void *v2, void *opaque);
406
407 /**
408    OID for the paged results control. This control is included in the
409    searchRequest and searchResultDone messages as part of the controls
410    field of the LDAPMessage, as defined in Section 4.1.12 of
411    LDAP v3. 
412
413    \sa <a href="http://www.ietf.org/rfc/rfc2696.txt">RFC 2696</a>.
414 */
415 #define LDB_CONTROL_PAGED_RESULTS_OID   "1.2.840.113556.1.4.319"
416
417 /**
418    OID for notification
419
420    \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>
421 */
422 #define LDB_CONTROL_NOTIFICATION_OID    "1.2.840.113556.1.4.528"
423
424 /**
425    OID for extended DN
426
427    \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>
428 */
429 #define LDB_CONTROL_EXTENDED_DN_OID     "1.2.840.113556.1.4.529"
430
431 /**
432    OID for LDAP server sort result extension.
433
434    This control is included in the searchRequest message as part of
435    the controls field of the LDAPMessage, as defined in Section 4.1.12
436    of LDAP v3. The controlType is set to
437    "1.2.840.113556.1.4.473". The criticality MAY be either TRUE or
438    FALSE (where absent is also equivalent to FALSE) at the client's
439    option.
440
441    \sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
442 */
443 #define LDB_CONTROL_SERVER_SORT_OID     "1.2.840.113556.1.4.473"
444
445 /**
446    OID for LDAP server sort result response extension.
447
448    This control is included in the searchResultDone message as part of
449    the controls field of the LDAPMessage, as defined in Section 4.1.12 of
450    LDAP v3.
451
452    \sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
453 */
454 #define LDB_CONTROL_SORT_RESP_OID       "1.2.840.113556.1.4.474"
455
456 /**
457    OID for LDAP Attribute Scoped Query extension.
458
459    This control is include in SearchRequest or SearchResponse
460    messages as part of the controls field of the LDAPMessage.
461 */
462 #define LDB_CONTROL_ASQ_OID             "1.2.840.113556.1.4.1504"
463
464 /**
465    OID for LDAPrectory Sync extension. 
466
467    This control is include in SearchRequest or SearchResponse
468    messages as part of the controls field of the LDAPMessage.
469 */
470 #define LDB_CONTROL_DIRSYNC_OID         "1.2.840.113556.1.4.841"
471
472
473 struct ldb_paged_control {
474         int size;
475         int cookie_len;
476         char *cookie;
477 };
478
479 struct ldb_extended_dn_control {
480         int type;
481 };
482
483 struct ldb_server_sort_control {
484         char *attributeName;
485         char *orderingRule;
486         int reverse;
487 };
488
489 struct ldb_sort_resp_control {
490         int result;
491         char *attr_desc;
492 };
493
494 struct ldb_asq_control {
495         int request;
496         char *source_attribute;
497         int src_attr_len;
498         int result;
499 };
500
501 struct ldb_dirsync_control {
502         int flags;
503         int max_attributes;
504         int cookie_len;
505         char *cookie;
506 };
507
508 struct ldb_control {
509         const char *oid;
510         int critical;
511         void *data;
512 };
513
514 struct ldb_credentials;
515
516 enum ldb_request_type {
517         LDB_REQ_SEARCH,
518         LDB_REQ_ADD,
519         LDB_REQ_MODIFY,
520         LDB_REQ_DELETE,
521         LDB_REQ_RENAME,
522         LDB_REQ_REGISTER
523 };
524
525 struct ldb_result {
526         unsigned int count;
527         struct ldb_message **msgs;
528         struct ldb_control **controls;
529 };
530
531 struct ldb_search {
532         const struct ldb_dn *base;
533         enum ldb_scope scope;
534         struct ldb_parse_tree *tree;
535         const char * const *attrs;
536         struct ldb_result *res;
537 };
538
539 struct ldb_add {
540         const struct ldb_message *message;
541 };
542
543 struct  ldb_modify {
544         const struct ldb_message *message;
545 };
546
547 struct ldb_delete {
548         const struct ldb_dn *dn;
549 };
550
551 struct ldb_rename {
552         const struct ldb_dn *olddn;
553         const struct ldb_dn *newdn;
554 };
555
556 struct ldb_register_control {
557         const char *oid;
558 };
559
560 struct ldb_request {
561
562         int operation;
563
564         union {
565                 struct ldb_search search;
566                 struct ldb_add    add;
567                 struct ldb_modify mod;
568                 struct ldb_delete del;
569                 struct ldb_rename rename;
570                 struct ldb_register_control reg;
571         } op;
572
573         struct ldb_control **controls;
574         struct ldb_credentials *creds;
575 };
576
577 int ldb_request(struct ldb_context *ldb, struct ldb_request *request);
578
579 /**
580   Initialise an ldb context
581
582   This is required before any other LDB call.
583
584   \param mem_ctx pointer to a talloc memory context. Pass NULL if there is
585   no suitable context available.
586
587   \return pointer to ldb_context that should be free'd (using talloc_free())
588   at the end of the program.
589 */
590 struct ldb_context *ldb_init(void *mem_ctx);
591
592 /**
593    Connect to a database.
594
595    This is typically called soon after ldb_init(), and is required prior to
596    any search or database modification operations.
597
598    The URL can be one of the following forms:
599     - tdb://path
600     - ldapi://path
601     - ldap://host
602     - sqlite://path
603
604    \param ldb the context associated with the database (from ldb_init())
605    \param url the URL of the database to connect to, as noted above
606    \param flags a combination of LDB_FLG_* to modify the connection behaviour
607    \param options backend specific options - passed uninterpreted to the backend
608
609    \return result code (LDB_SUCCESS on success, or a failure code)
610
611    \note It is an error to connect to a database that does not exist in readonly mode
612    (that is, with LDB_FLG_RDONLY). However in read-write mode, the database will be
613    created if it does not exist.
614 */
615 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
616
617 /**
618   Search the database
619
620   This function searches the database, and returns 
621   records that match an LDAP-like search expression
622
623   \param ldb the context associated with the database (from ldb_init())
624   \param base the Base Distinguished Name for the query (pass NULL for root DN)
625   \param scope the search scope for the query
626   \param expression the search expression to use for this query
627   \param attrs the search attributes for the query (pass NULL if none required)
628   \param res the return result
629
630   \return result code (LDB_SUCCESS on success, or a failure code)
631
632   \note use talloc_free() to free the ldb_result returned
633 */
634 int ldb_search(struct ldb_context *ldb, 
635                const struct ldb_dn *base,
636                enum ldb_scope scope,
637                const char *expression,
638                const char * const *attrs, struct ldb_result **res);
639
640 /*
641   like ldb_search() but takes a parse tree
642 */
643 int ldb_search_bytree(struct ldb_context *ldb, 
644                       const struct ldb_dn *base,
645                       enum ldb_scope scope,
646                       struct ldb_parse_tree *tree,
647                       const char * const *attrs, struct ldb_result **res);
648
649 /**
650   Add a record to the database.
651
652   This function adds a record to the database. This function will fail
653   if a record with the specified class and key already exists in the
654   database. 
655
656   \param ldb the context associated with the database (from
657   ldb_init())
658   \param message the message containing the record to add.
659
660   \return result code (LDB_SUCCESS if the record was added, otherwise
661   a failure code)
662 */
663 int ldb_add(struct ldb_context *ldb, 
664             const struct ldb_message *message);
665
666 /**
667   Modify the specified attributes of a record
668
669   This function modifies a record that is in the database.
670
671   \param ldb the context associated with the database (from
672   ldb_init())
673   \param message the message containing the changes required.
674
675   \return result code (LDB_SUCCESS if the record was modified as
676   requested, otherwise a failure code)
677 */
678 int ldb_modify(struct ldb_context *ldb, 
679                const struct ldb_message *message);
680
681 /**
682   Rename a record in the database
683
684   This function renames a record in the database.
685
686   \param ldb the context associated with the database (from
687   ldb_init())
688   \param olddn the DN for the record to be renamed.
689   \param newdn the new DN 
690
691   \return result code (LDB_SUCCESS if the record was renamed as
692   requested, otherwise a failure code)
693 */
694 int ldb_rename(struct ldb_context *ldb, const struct ldb_dn *olddn, const struct ldb_dn *newdn);
695
696 /**
697   Delete a record from the database
698
699   This function deletes a record from the database.
700
701   \param ldb the context associated with the database (from
702   ldb_init())
703   \param dn the DN for the record to be deleted.
704
705   \return result code (LDB_SUCCESS if the record was deleted,
706   otherwise a failure code)
707 */
708 int ldb_delete(struct ldb_context *ldb, const struct ldb_dn *dn);
709
710 /**
711   start a transaction
712 */
713 int ldb_transaction_start(struct ldb_context *ldb);
714
715 /**
716   commit a transaction
717 */
718 int ldb_transaction_commit(struct ldb_context *ldb);
719
720 /**
721   cancel a transaction
722 */
723 int ldb_transaction_cancel(struct ldb_context *ldb);
724
725
726 /**
727   return extended error information from the last call
728 */
729 const char *ldb_errstring(struct ldb_context *ldb);
730
731 /**
732   setup the default utf8 functions
733   FIXME: these functions do not yet handle utf8
734 */
735 void ldb_set_utf8_default(struct ldb_context *ldb);
736
737 /**
738    Casefold a string
739
740    \param ldb the ldb context
741    \param mem_ctx the memory context to allocate the result string
742    memory from. 
743    \param s the string that is to be folded
744    \return a copy of the string, converted to upper case
745
746    \note The default function is not yet UTF8 aware. Provide your own
747          set of functions through ldb_set_utf8_fns()
748 */
749 char *ldb_casefold(struct ldb_context *ldb, void *mem_ctx, const char *s);
750
751 /**
752    Compare two strings, without regard to case. 
753
754    \param ldb the ldb context
755    \param s1 the first string to compare
756    \param s2 the second string to compare
757
758    \return 0 if the strings are the same, non-zero if there are any
759    differences except for case.
760
761    \note The default function is not yet UTF8 aware. Provide your own
762          set of functions through ldb_set_utf8_fns()
763 */
764 int ldb_caseless_cmp(struct ldb_context *ldb, const char *s1, const char *s2);
765
766 /**
767    Check the attribute name is valid according to rfc2251
768    \param s tthe string to check
769
770    \return 1 if the name is ok
771 */
772 int ldb_valid_attr_name(const char *s);
773
774 /*
775   ldif manipulation functions
776 */
777 /**
778    Write an LDIF message
779
780    This function writes an LDIF message using a caller supplied  write
781    function.
782
783    \param ldb the ldb context (from ldb_init())
784    \param fprintf_fn a function pointer for the write function. This must take
785    a private data pointer, followed by a format string, and then a variable argument
786    list. 
787    \param private_data pointer that will be provided back to the write
788    function. This is useful for maintaining state or context.
789    \param ldif the message to write out
790
791    \return the total number of bytes written, or an error code as returned
792    from the write function.
793
794    \sa ldb_ldif_write_file for a more convenient way to write to a
795    file stream.
796
797    \sa ldb_ldif_read for the reader equivalent to this function.
798 */
799 int ldb_ldif_write(struct ldb_context *ldb,
800                    int (*fprintf_fn)(void *, const char *, ...), 
801                    void *private_data,
802                    const struct ldb_ldif *ldif);
803
804 /**
805    Clean up an LDIF message
806
807    This function cleans up a LDIF message read using ldb_ldif_read()
808    or related functions (such as ldb_ldif_read_string() and
809    ldb_ldif_read_file().
810
811    \param ldb the ldb context (from ldb_init())
812    \param msg the message to clean up and free
813
814 */
815 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *msg);
816
817 /**
818    Read an LDIF message
819
820    This function creates an LDIF message using a caller supplied read
821    function. 
822
823    \param ldb the ldb context (from ldb_init())
824    \param fgetc_fn a function pointer for the read function. This must
825    take a private data pointer, and must return a pointer to an
826    integer corresponding to the next byte read (or EOF if there is no
827    more data to be read).
828    \param private_data pointer that will be provided back to the read
829    function. This is udeful for maintaining state or context.
830
831    \return the LDIF message that has been read in
832
833    \note You must free the LDIF message when no longer required, using
834    ldb_ldif_read_free().
835
836    \sa ldb_ldif_read_file for a more convenient way to read from a
837    file stream.
838
839    \sa ldb_ldif_read_string for a more convenient way to read from a
840    string (char array).
841
842    \sa ldb_ldif_write for the writer equivalent to this function.
843 */
844 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb, 
845                                int (*fgetc_fn)(void *), void *private_data);
846
847 /**
848    Read an LDIF message from a file
849
850    This function reads the next LDIF message from the contents of a
851    file stream. If you want to get all of the LDIF messages, you will
852    need to repeatedly call this function, until it returns NULL.
853
854    \param ldb the ldb context (from ldb_init())
855    \param f the file stream to read from (typically from fdopen())
856
857    \sa ldb_ldif_read_string for an equivalent function that will read
858    from a string (char array).
859
860    \sa ldb_ldif_write_file for the writer equivalent to this function.
861
862 */
863 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
864
865 /**
866    Read an LDIF message from a string
867
868    This function reads the next LDIF message from the contents of a char
869    array. If you want to get all of the LDIF messages, you will need
870    to repeatedly call this function, until it returns NULL.
871
872    \param ldb the ldb context (from ldb_init())
873    \param s pointer to the char array to read from
874
875    \sa ldb_ldif_read_file for an equivalent function that will read
876    from a file stream.
877
878    \sa ldb_ldif_write for a more general (arbitrary read function)
879    version of this function.
880 */
881 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
882
883 /**
884    Write an LDIF message to a file
885
886    \param ldb the ldb context (from ldb_init())
887    \param f the file stream to write to (typically from fdopen())
888    \param msg the message to write out
889
890    \return the total number of bytes written, or a negative error code
891
892    \sa ldb_ldif_read_file for the reader equivalent to this function.
893 */
894 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
895
896 /**
897    Base64 encode a buffer
898
899    \param mem_ctx the memory context that the result is allocated
900    from. 
901    \param buf pointer to the array that is to be encoded
902    \param len the number of elements in the array to be encoded
903
904    \return pointer to an array containing the encoded data
905
906    \note The caller is responsible for freeing the result
907 */
908 char *ldb_base64_encode(void *mem_ctx, const char *buf, int len);
909
910 /**
911    Base64 decode a buffer
912
913    This function decodes a base64 encoded string in place.
914
915    \param s the string to decode.
916
917    \return the length of the returned (decoded) string.
918
919    \note the string is null terminated, but the null terminator is not
920    included in the length.
921 */
922 int ldb_base64_decode(char *s);
923
924 int ldb_attrib_add_handlers(struct ldb_context *ldb, 
925                             const struct ldb_attrib_handler *handlers, 
926                             unsigned num_handlers);
927
928 /* The following definitions come from lib/ldb/common/ldb_dn.c  */
929
930 int ldb_dn_is_special(const struct ldb_dn *dn);
931 int ldb_dn_check_special(const struct ldb_dn *dn, const char *check);
932 char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
933 struct ldb_dn *ldb_dn_new(void *mem_ctx);
934 struct ldb_dn *ldb_dn_explode(void *mem_ctx, const char *dn);
935 struct ldb_dn *ldb_dn_explode_or_special(void *mem_ctx, const char *dn);
936 char *ldb_dn_linearize(void *mem_ctx, const struct ldb_dn *edn);
937 char *ldb_dn_linearize_casefold(struct ldb_context *ldb, const struct ldb_dn *edn);
938 int ldb_dn_compare_base(struct ldb_context *ldb, const struct ldb_dn *base, const struct ldb_dn *dn);
939 int ldb_dn_compare(struct ldb_context *ldb, const struct ldb_dn *edn0, const struct ldb_dn *edn1);
940 struct ldb_dn *ldb_dn_casefold(struct ldb_context *ldb, const struct ldb_dn *edn);
941 struct ldb_dn *ldb_dn_explode_casefold(struct ldb_context *ldb, const char *dn);
942 struct ldb_dn *ldb_dn_copy_partial(void *mem_ctx, const struct ldb_dn *dn, int num_el);
943 struct ldb_dn *ldb_dn_copy(void *mem_ctx, const struct ldb_dn *dn);
944 struct ldb_dn *ldb_dn_get_parent(void *mem_ctx, const struct ldb_dn *dn);
945 struct ldb_dn_component *ldb_dn_build_component(void *mem_ctx, const char *attr,
946                                                                const char *val);
947 struct ldb_dn *ldb_dn_build_child(void *mem_ctx, const char *attr,
948                                                  const char * value,
949                                                  const struct ldb_dn *base);
950 struct ldb_dn *ldb_dn_make_child(void *mem_ctx,
951                                  const struct ldb_dn_component *component,
952                                  const struct ldb_dn *base);
953 struct ldb_dn *ldb_dn_compose(void *mem_ctx, const struct ldb_dn *dn1, const struct ldb_dn *dn2);
954 struct ldb_dn *ldb_dn_string_compose(void *mem_ctx, const struct ldb_dn *base, const char *child_fmt, ...) PRINTF_ATTRIBUTE(3,4);
955 struct ldb_dn_component *ldb_dn_get_rdn(void *mem_ctx, const struct ldb_dn *dn);
956
957 /* useful functions for ldb_message structure manipulation */
958 int ldb_dn_cmp(struct ldb_context *ldb, const char *dn1, const char *dn2);
959
960 /**
961    Compare two attributes
962
963    This function compares to attribute names. Note that this is a
964    case-insensitive comparison.
965
966    \param attr1 the first attribute name to compare
967    \param attr2 the second attribute name to compare
968
969    \return 0 if the attribute names are the same, or only differ in
970    case; non-zero if there are any differences
971 */
972 int ldb_attr_cmp(const char *attr1, const char *attr2);
973 int ldb_attr_dn(const char *attr);
974 char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
975
976 /**
977    Create an empty message
978
979    \param mem_ctx the memory context to create in. You can pass NULL
980    to get the top level context, however the ldb context (from
981    ldb_init()) may be a better choice
982 */
983 struct ldb_message *ldb_msg_new(void *mem_ctx);
984
985 /**
986    Find an element within an message
987 */
988 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg, 
989                                                  const char *attr_name);
990
991 /**
992    Compare two ldb_val values
993
994    \param v1 first ldb_val structure to be tested
995    \param v2 second ldb_val structure to be tested
996
997    \return 1 for a match, 0 if there is any difference
998 */
999 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
1000
1001 /**
1002    find a value within an ldb_message_element
1003
1004    \param el the element to search
1005    \param val the value to search for
1006
1007    \note This search is case sensitive
1008 */
1009 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el, 
1010                                  struct ldb_val *val);
1011
1012 /**
1013    add a new empty element to a ldb_message
1014 */
1015 int ldb_msg_add_empty(struct ldb_message *msg, const char *attr_name, int flags);
1016
1017 /**
1018    add a element to a ldb_message
1019 */
1020 int ldb_msg_add(struct ldb_message *msg, 
1021                 const struct ldb_message_element *el, 
1022                 int flags);
1023 int ldb_msg_add_value(struct ldb_message *msg, 
1024                       const char *attr_name,
1025                       const struct ldb_val *val);
1026 int ldb_msg_add_string(struct ldb_message *msg, 
1027                        const char *attr_name, const char *str);
1028 int ldb_msg_add_fmt(struct ldb_message *msg, 
1029                     const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
1030
1031 /**
1032    compare two message elements - return 0 on match
1033 */
1034 int ldb_msg_element_compare(struct ldb_message_element *el1, 
1035                             struct ldb_message_element *el2);
1036
1037 /**
1038    Find elements in a message.
1039
1040    This function finds elements and converts to a specific type, with
1041    a give default value if not found. Assumes that elements are
1042    single valued.
1043 */
1044 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
1045 int ldb_msg_find_int(const struct ldb_message *msg, 
1046                      const char *attr_name,
1047                      int default_value);
1048 unsigned int ldb_msg_find_uint(const struct ldb_message *msg, 
1049                                const char *attr_name,
1050                                unsigned int default_value);
1051 int64_t ldb_msg_find_int64(const struct ldb_message *msg, 
1052                            const char *attr_name,
1053                            int64_t default_value);
1054 uint64_t ldb_msg_find_uint64(const struct ldb_message *msg, 
1055                              const char *attr_name,
1056                              uint64_t default_value);
1057 double ldb_msg_find_double(const struct ldb_message *msg, 
1058                            const char *attr_name,
1059                            double default_value);
1060 const char *ldb_msg_find_string(const struct ldb_message *msg, 
1061                                 const char *attr_name,
1062                                 const char *default_value);
1063
1064 void ldb_msg_sort_elements(struct ldb_message *msg);
1065
1066 struct ldb_message *ldb_msg_copy_shallow(void *mem_ctx, 
1067                                          const struct ldb_message *msg);
1068 struct ldb_message *ldb_msg_copy(void *mem_ctx, 
1069                                  const struct ldb_message *msg);
1070
1071 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb, 
1072                                          const struct ldb_message *msg);
1073
1074
1075 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb, 
1076                                  struct ldb_message *msg1,
1077                                  struct ldb_message *msg2);
1078
1079 /**
1080    Integrity check an ldb_message
1081
1082    This function performs basic sanity / integrity checks on an
1083    ldb_message.
1084
1085    \param msg the message to check
1086
1087    \return LDB_SUCCESS if the message is OK, or a non-zero error code
1088    (one of LDB_ERR_INVALID_DN_SYNTAX, LDB_ERR_ENTRY_ALREADY_EXISTS or
1089    LDB_ERR_INVALID_ATTRIBUTE_SYNTAX) if there is a problem with a
1090    message.
1091 */
1092 int ldb_msg_sanity_check(const struct ldb_message *msg);
1093
1094 /**
1095    Duplicate an ldb_val structure
1096
1097    This function copies an ldb value structure. 
1098
1099    \param mem_ctx the memory context that the duplicated value will be
1100    allocated from
1101    \param v the ldb_val to be duplicated.
1102
1103    \return the duplicated ldb_val structure.
1104 */
1105 struct ldb_val ldb_val_dup(void *mem_ctx, const struct ldb_val *v);
1106
1107 /**
1108   this allows the user to set a debug function for error reporting
1109 */
1110 int ldb_set_debug(struct ldb_context *ldb,
1111                   void (*debug)(void *context, enum ldb_debug_level level, 
1112                                 const char *fmt, va_list ap),
1113                   void *context);
1114
1115 /**
1116    this sets up debug to print messages on stderr
1117 */
1118 int ldb_set_debug_stderr(struct ldb_context *ldb);
1119
1120 /* control backend specific opaque values */
1121 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
1122 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
1123
1124 const struct ldb_attrib_handler *ldb_attrib_handler(struct ldb_context *ldb,
1125                                                     const char *attrib);
1126
1127
1128 const char **ldb_attr_list_copy(void *mem_ctx, const char * const *attrs);
1129 int ldb_attr_in_list(const char * const *attrs, const char *attr);
1130
1131
1132 void ldb_parse_tree_attr_replace(struct ldb_parse_tree *tree, 
1133                                  const char *attr, 
1134                                  const char *replace);
1135
1136 int ldb_msg_rename_attr(struct ldb_message *msg, const char *attr, const char *replace);
1137 int ldb_msg_copy_attr(struct ldb_message *msg, const char *attr, const char *replace);
1138 void ldb_msg_remove_attr(struct ldb_message *msg, const char *attr);
1139
1140 /**
1141    Convert a time structure to a string
1142
1143    This function converts a time_t structure to an LDAP formatted time
1144    string.
1145
1146    \param mem_ctx the memory context to allocate the return string in
1147    \param t the time structure to convert
1148
1149    \return the formatted string, or NULL if the time structure could
1150    not be converted
1151 */
1152 char *ldb_timestring(void *mem_ctx, time_t t);
1153
1154 /**
1155    Convert a string to a time structure
1156
1157    This function converts an LDAP formatted time string to a time_t
1158    structure.
1159
1160    \param s the string to convert
1161
1162    \return the time structure, or 0 if the string cannot be converted
1163 */
1164 time_t ldb_string_to_time(const char *s);
1165
1166 char *ldb_dn_canonical_string(void *mem_ctx, const struct ldb_dn *dn);
1167 char *ldb_dn_canonical_ex_string(void *mem_ctx, const struct ldb_dn *dn);
1168
1169
1170 void ldb_qsort (void *const pbase, size_t total_elems, size_t size, void *opaque, ldb_qsort_cmp_fn_t cmp);
1171 #endif