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