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 allows the user to set custom utf8 function for error reporting
1117 */
1118 void ldb_set_utf8_fns(struct ldb_context *ldb,
1119                         void *context,
1120                         int (*cmp)(void *, const char *, const char *),
1121                         char *(*casefold)(void *, void *, const char *));
1122
1123 /**
1124    this sets up debug to print messages on stderr
1125 */
1126 int ldb_set_debug_stderr(struct ldb_context *ldb);
1127
1128 /* control backend specific opaque values */
1129 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
1130 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
1131
1132 const struct ldb_attrib_handler *ldb_attrib_handler(struct ldb_context *ldb,
1133                                                     const char *attrib);
1134
1135
1136 const char **ldb_attr_list_copy(void *mem_ctx, const char * const *attrs);
1137 int ldb_attr_in_list(const char * const *attrs, const char *attr);
1138
1139
1140 void ldb_parse_tree_attr_replace(struct ldb_parse_tree *tree,
1141                                  const char *attr,
1142                                  const char *replace);
1143
1144 int ldb_msg_rename_attr(struct ldb_message *msg, const char *attr, const char *replace);
1145 int ldb_msg_copy_attr(struct ldb_message *msg, const char *attr, const char *replace);
1146 void ldb_msg_remove_attr(struct ldb_message *msg, const char *attr);
1147
1148 /**
1149    Convert a time structure to a string
1150
1151    This function converts a time_t structure to an LDAP formatted time
1152    string.
1153
1154    \param mem_ctx the memory context to allocate the return string in
1155    \param t the time structure to convert
1156
1157    \return the formatted string, or NULL if the time structure could
1158    not be converted
1159 */
1160 char *ldb_timestring(void *mem_ctx, time_t t);
1161
1162 /**
1163    Convert a string to a time structure
1164
1165    This function converts an LDAP formatted time string to a time_t
1166    structure.
1167
1168    \param s the string to convert
1169
1170    \return the time structure, or 0 if the string cannot be converted
1171 */
1172 time_t ldb_string_to_time(const char *s);
1173
1174 char *ldb_dn_canonical_string(void *mem_ctx, const struct ldb_dn *dn);
1175 char *ldb_dn_canonical_ex_string(void *mem_ctx, const struct ldb_dn *dn);
1176
1177
1178 void ldb_qsort (void *const pbase, size_t total_elems, size_t size, void *opaque, ldb_qsort_cmp_fn_t cmp);
1179 #endif