lib/ldb/include/ldb.h

   1 /*
   2    ldb database library
   3
   4    Copyright (C) Andrew Tridgell  2004
   5    Copyright (C) Stefan Metzmacher  2004
   6    Copyright (C) Simo Sorce  2005-2006
   7
   8      ** NOTE! The following LGPL license applies to the ldb
   9      ** library. This does NOT imply that all of Samba is released
  10      ** under the LGPL
  11
  12    This library is free software; you can redistribute it and/or
  13    modify it under the terms of the GNU Lesser General Public
  14    License as published by the Free Software Foundation; either
  15    version 3 of the License, or (at your option) any later version.
  16
  17    This library is distributed in the hope that it will be useful,
  18    but WITHOUT ANY WARRANTY; without even the implied warranty of
  19    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20    Lesser General Public License for more details.
  21
  22    You should have received a copy of the GNU Lesser General Public
  23    License along with this library; if not, see <http://www.gnu.org/licenses/>.
  24 */
  25
  26 /*
  27  *  Name: ldb
  28  *
  29  *  Component: ldb header
  30  *
  31  *  Description: defines for base ldb API
  32  *
  33  *  Author: Andrew Tridgell
  34  *  Author: Stefan Metzmacher
  35  */
  36
  37 /**
  38    \file ldb.h Samba's ldb database
  39
  40    This header file provides the main API for ldb.
  41 */
  42
  43 #ifndef _LDB_H_
  44
  45 /*! \cond DOXYGEN_IGNORE */
  46 #define _LDB_H_ 1
  47 /*! \endcond */
  48
  49 #include <stdbool.h>
  50 #include <talloc.h>
  51 #include <tevent.h>
  52 #include <ldb_version.h>
  53 #include <ldb_errors.h>
  54
  55 /*
  56   major restrictions as compared to normal LDAP:
  57
  58      - each record must have a unique key field
  59      - the key must be representable as a NULL terminated C string and may not
  60        contain a comma or braces
  61
  62   major restrictions as compared to tdb:
  63
  64      - no explicit locking calls, but we have transactions when using ldb_tdb
  65
  66 */
  67
  68 #ifndef ldb_val
  69 /**
  70    Result value
  71
  72    An individual lump of data in a result comes in this format. The
  73    pointer will usually be to a UTF-8 string if the application is
  74    sensible, but it can be to anything you like, including binary data
  75    blobs of arbitrary size.
  76
  77    \note the data is null (0x00) terminated, but the length does not
  78    include the terminator.
  79 */
  80 struct ldb_val {
  81         uint8_t *data; /*!< result data */
  82         size_t length; /*!< length of data */
  83 };
  84 #endif
  85
  86 /*! \cond DOXYGEN_IGNORE */
  87 #ifndef PRINTF_ATTRIBUTE
  88 #define PRINTF_ATTRIBUTE(a,b)
  89 #endif
  90
  91 #ifndef _DEPRECATED_
  92 #if (__GNUC__ >= 3) && (__GNUC_MINOR__ >= 1 )
  93 #define _DEPRECATED_ __attribute__ ((deprecated))
  94 #else
  95 #define _DEPRECATED_
  96 #endif
  97 #endif
  98 /*! \endcond */
  99
 100 /* opaque ldb_dn structures, see ldb_dn.c for internals */
 101 struct ldb_dn_component;
 102 struct ldb_dn;
 103
 104 /**
 105  There are a number of flags that are used with ldap_modify() in
 106  ldb_message_element.flags fields. The LDB_FLAG_MOD_ADD,
 107  LDB_FLAG_MOD_DELETE and LDB_FLAG_MOD_REPLACE flags are used in
 108  ldap_modify() calls to specify whether attributes are being added,
 109  deleted or modified respectively.
 110 */
 111 #define LDB_FLAG_MOD_MASK  0x3
 112
 113 /**
 114   use this to extract the mod type from the operation
 115  */
 116 #define LDB_FLAG_MOD_TYPE(flags) ((flags) & LDB_FLAG_MOD_MASK)
 117
 118 /**
 119    Flag value used in ldap_modify() to indicate that attributes are
 120    being added.
 121
 122    \sa LDB_FLAG_MOD_MASK
 123 */
 124 #define LDB_FLAG_MOD_ADD     1
 125
 126 /**
 127    Flag value used in ldap_modify() to indicate that attributes are
 128    being replaced.
 129
 130    \sa LDB_FLAG_MOD_MASK
 131 */
 132 #define LDB_FLAG_MOD_REPLACE 2
 133
 134 /**
 135    Flag value used in ldap_modify() to indicate that attributes are
 136    being deleted.
 137
 138    \sa LDB_FLAG_MOD_MASK
 139 */
 140 #define LDB_FLAG_MOD_DELETE  3
 141
 142 /**
 143     flag bits on an element usable only by the internal implementation
 144 */
 145 #define LDB_FLAG_INTERNAL_MASK 0xFFFFFFF0
 146
 147 /**
 148   OID for logic AND comaprison.
 149
 150   This is the well known object ID for a logical AND comparitor.
 151 */
 152 #define LDB_OID_COMPARATOR_AND  "1.2.840.113556.1.4.803"
 153
 154 /**
 155   OID for logic OR comparison.
 156
 157   This is the well known object ID for a logical OR comparitor.
 158 */
 159 #define LDB_OID_COMPARATOR_OR   "1.2.840.113556.1.4.804"
 160
 161 /**
 162   results are given back as arrays of ldb_message_element
 163 */
 164 struct ldb_message_element {
 165         unsigned int flags;
 166         const char *name;
 167         unsigned int num_values;
 168         struct ldb_val *values;
 169 };
 170
 171
 172 /**
 173   a ldb_message represents all or part of a record. It can contain an arbitrary
 174   number of elements.
 175 */
 176 struct ldb_message {
 177         struct ldb_dn *dn;
 178         unsigned int num_elements;
 179         struct ldb_message_element *elements;
 180 };
 181
 182 enum ldb_changetype {
 183         LDB_CHANGETYPE_NONE=0,
 184         LDB_CHANGETYPE_ADD,
 185         LDB_CHANGETYPE_DELETE,
 186         LDB_CHANGETYPE_MODIFY,
 187         LDB_CHANGETYPE_MODRDN
 188 };
 189
 190 /**
 191   LDIF record
 192
 193   This structure contains a LDIF record, as returned from ldif_read()
 194   and equivalent functions.
 195 */
 196 struct ldb_ldif {
 197         enum ldb_changetype changetype; /*!< The type of change */
 198         struct ldb_message *msg;  /*!< The changes */
 199 };
 200
 201 enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
 202                 LDB_SCOPE_BASE=0,
 203                 LDB_SCOPE_ONELEVEL=1,
 204                 LDB_SCOPE_SUBTREE=2};
 205
 206 struct ldb_context;
 207 struct tevent_context;
 208
 209 /* debugging uses one of the following levels */
 210 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR,
 211                       LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
 212
 213 /**
 214   the user can optionally supply a debug function. The function
 215   is based on the vfprintf() style of interface, but with the addition
 216   of a severity level
 217 */
 218 struct ldb_debug_ops {
 219         void (*debug)(void *context, enum ldb_debug_level level,
 220                       const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0);
 221         void *context;
 222 };
 223
 224 /**
 225   The user can optionally supply a custom utf8 functions,
 226   to handle comparisons and casefolding.
 227 */
 228 struct ldb_utf8_fns {
 229         void *context;
 230         char *(*casefold)(void *context, TALLOC_CTX *mem_ctx, const char *s, size_t n);
 231 };
 232
 233 /**
 234    Flag value for database connection mode.
 235
 236    If LDB_FLG_RDONLY is used in ldb_connect, then the database will be
 237    opened read-only, if possible.
 238 */
 239 #define LDB_FLG_RDONLY 1
 240
 241 /**
 242    Flag value for database connection mode.
 243
 244    If LDB_FLG_NOSYNC is used in ldb_connect, then the database will be
 245    opened without synchronous operations, if possible.
 246 */
 247 #define LDB_FLG_NOSYNC 2
 248
 249 /**
 250    Flag value to specify autoreconnect mode.
 251
 252    If LDB_FLG_RECONNECT is used in ldb_connect, then the backend will
 253    be opened in a way that makes it try to auto reconnect if the
 254    connection is dropped (actually make sense only with ldap).
 255 */
 256 #define LDB_FLG_RECONNECT 4
 257
 258 /**
 259    Flag to tell backends not to use mmap
 260 */
 261 #define LDB_FLG_NOMMAP 8
 262
 263 /**
 264    Flag to tell ldif handlers not to force encoding of binary
 265    structures in base64
 266 */
 267 #define LDB_FLG_SHOW_BINARY 16
 268
 269 /**
 270    Flags to enable ldb tracing
 271 */
 272 #define LDB_FLG_ENABLE_TRACING 32
 273
 274 /**
 275    Flags to tell LDB not to create a new database file:
 276
 277    Without this flag ldb_tdb (for example) will create a blank file
 278    during an invocation of ldb_connect(), even when the caller only
 279    wanted read operations, for example in ldbsearch.
 280 */
 281 #define LDB_FLG_DONT_CREATE_DB 64
 282
 283 /*
 284    structures for ldb_parse_tree handling code
 285 */
 286 enum ldb_parse_op { LDB_OP_AND=1, LDB_OP_OR=2, LDB_OP_NOT=3,
 287                     LDB_OP_EQUALITY=4, LDB_OP_SUBSTRING=5,
 288                     LDB_OP_GREATER=6, LDB_OP_LESS=7, LDB_OP_PRESENT=8,
 289                     LDB_OP_APPROX=9, LDB_OP_EXTENDED=10 };
 290
 291 struct ldb_parse_tree {
 292         enum ldb_parse_op operation;
 293         union {
 294                 struct {
 295                         struct ldb_parse_tree *child;
 296                 } isnot;
 297                 struct {
 298                         const char *attr;
 299                         struct ldb_val value;
 300                 } equality;
 301                 struct {
 302                         const char *attr;
 303                         int start_with_wildcard;
 304                         int end_with_wildcard;
 305                         struct ldb_val **chunks;
 306                 } substring;
 307                 struct {
 308                         const char *attr;
 309                 } present;
 310                 struct {
 311                         const char *attr;
 312                         struct ldb_val value;
 313                 } comparison;
 314                 struct {
 315                         const char *attr;
 316                         int dnAttributes;
 317                         const char *rule_id;
 318                         struct ldb_val value;
 319                 } extended;
 320                 struct {
 321                         unsigned int num_elements;
 322                         struct ldb_parse_tree **elements;
 323                 } list;
 324         } u;
 325 };
 326
 327 struct ldb_parse_tree *ldb_parse_tree(TALLOC_CTX *mem_ctx, const char *s);
 328 char *ldb_filter_from_tree(TALLOC_CTX *mem_ctx, const struct ldb_parse_tree *tree);
 329
 330 /**
 331    Encode a binary blob
 332
 333    This function encodes a binary blob using the encoding rules in RFC
 334    2254 (Section 4). This function also escapes any non-printable
 335    characters.
 336
 337    \param mem_ctx the memory context to allocate the return string in.
 338    \param val the (potentially) binary data to be encoded
 339
 340    \return the encoded data as a null terminated string
 341
 342    \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>.
 343 */
 344 char *ldb_binary_encode(TALLOC_CTX *mem_ctx, struct ldb_val val);
 345
 346 /**
 347    Encode a string
 348
 349    This function encodes a string using the encoding rules in RFC 2254
 350    (Section 4). This function also escapes any non-printable
 351    characters.
 352
 353    \param mem_ctx the memory context to allocate the return string in.
 354    \param string the string to be encoded
 355
 356    \return the encoded data as a null terminated string
 357
 358    \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>.
 359 */
 360 char *ldb_binary_encode_string(TALLOC_CTX *mem_ctx, const char *string);
 361
 362 /*
 363   functions for controlling attribute handling
 364 */
 365 typedef int (*ldb_attr_handler_t)(struct ldb_context *, TALLOC_CTX *mem_ctx, const struct ldb_val *, struct ldb_val *);
 366 typedef int (*ldb_attr_comparison_t)(struct ldb_context *, TALLOC_CTX *mem_ctx, const struct ldb_val *, const struct ldb_val *);
 367 struct ldb_schema_attribute;
 368 typedef int (*ldb_attr_operator_t)(struct ldb_context *, enum ldb_parse_op operation,
 369                                    const struct ldb_schema_attribute *a,
 370                                    const struct ldb_val *, const struct ldb_val *, bool *matched);
 371
 372 /*
 373   attribute handler structure
 374
 375   attr                  -> The attribute name
 376   ldif_read_fn          -> convert from ldif to binary format
 377   ldif_write_fn         -> convert from binary to ldif format
 378   canonicalise_fn       -> canonicalise a value, for use by indexing and dn construction
 379   index_form_fn         -> get lexicographically sorted format for index
 380   comparison_fn         -> compare two values
 381   operator_fn           -> override function for optimizing out unnecessary
 382                                 calls to canonicalise_fn and comparison_fn
 383 */
 384
 385 struct ldb_schema_syntax {
 386         const char *name;
 387         ldb_attr_handler_t ldif_read_fn;
 388         ldb_attr_handler_t ldif_write_fn;
 389         ldb_attr_handler_t canonicalise_fn;
 390         ldb_attr_handler_t index_format_fn;
 391         ldb_attr_comparison_t comparison_fn;
 392         ldb_attr_operator_t operator_fn;
 393 };
 394
 395 struct ldb_schema_attribute {
 396         const char *name;
 397         unsigned flags;
 398         const struct ldb_schema_syntax *syntax;
 399 };
 400
 401 const struct ldb_schema_attribute *ldb_schema_attribute_by_name(struct ldb_context *ldb,
 402                                                                 const char *name);
 403
 404 struct ldb_dn_extended_syntax {
 405         const char *name;
 406         ldb_attr_handler_t read_fn;
 407         ldb_attr_handler_t write_clear_fn;
 408         ldb_attr_handler_t write_hex_fn;
 409 };
 410
 411 const struct ldb_dn_extended_syntax *ldb_dn_extended_syntax_by_name(struct ldb_context *ldb,
 412                                                                     const char *name);
 413
 414 /**
 415    The attribute is not returned by default
 416 */
 417 #define LDB_ATTR_FLAG_HIDDEN       (1<<0)
 418
 419 /* the attribute handler name should be freed when released */
 420 #define LDB_ATTR_FLAG_ALLOCATED    (1<<1)
 421
 422 /**
 423    The attribute is supplied by the application and should not be removed
 424 */
 425 #define LDB_ATTR_FLAG_FIXED        (1<<2)
 426
 427 /*
 428   when this is set, attempts to create two records which have the same
 429   value for this attribute will return LDB_ERR_ENTRY_ALREADY_EXISTS
 430  */
 431 #define LDB_ATTR_FLAG_UNIQUE_INDEX (1<<3)
 432
 433 /*
 434   when this is set, attempts to create two attribute values for this attribute on a single DN will return LDB_ERR_CONSTRAINT_VIOLATION
 435  */
 436 #define LDB_ATTR_FLAG_SINGLE_VALUE (1<<4)
 437
 438 /*
 439  * The values should always be base64 encoded
 440  */
 441 #define LDB_ATTR_FLAG_FORCE_BASE64_LDIF        (1<<5)
 442
 443 /*
 444  * The attribute was loaded from a DB, rather than via the C API
 445  */
 446 #define LDB_ATTR_FLAG_FROM_DB      (1<<6)
 447
 448 /*
 449  * The attribute is indexed
 450  */
 451 #define LDB_ATTR_FLAG_INDEXED      (1<<7)
 452
 453 /**
 454   LDAP attribute syntax for a DN
 455
 456   This is the well-known LDAP attribute syntax for a DN.
 457
 458   See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
 459 */
 460 #define LDB_SYNTAX_DN                   "1.3.6.1.4.1.1466.115.121.1.12"
 461
 462 /**
 463   LDAP attribute syntax for a Directory String
 464
 465   This is the well-known LDAP attribute syntax for a Directory String.
 466
 467   \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
 468 */
 469 #define LDB_SYNTAX_DIRECTORY_STRING     "1.3.6.1.4.1.1466.115.121.1.15"
 470
 471 /**
 472   LDAP attribute syntax for an integer
 473
 474   This is the well-known LDAP attribute syntax for an integer.
 475
 476   See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
 477 */
 478 #define LDB_SYNTAX_INTEGER              "1.3.6.1.4.1.1466.115.121.1.27"
 479
 480 /**
 481   Custom attribute syntax for an integer whose index is lexicographically
 482   ordered by attribute value in the database.
 483 */
 484 #define LDB_SYNTAX_ORDERED_INTEGER      "LDB_SYNTAX_ORDERED_INTEGER"
 485
 486 /**
 487   LDAP attribute syntax for a boolean
 488
 489   This is the well-known LDAP attribute syntax for a boolean.
 490
 491   See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
 492 */
 493 #define LDB_SYNTAX_BOOLEAN              "1.3.6.1.4.1.1466.115.121.1.7"
 494
 495 /**
 496   LDAP attribute syntax for an octet string
 497
 498   This is the well-known LDAP attribute syntax for an octet string.
 499
 500   See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
 501 */
 502 #define LDB_SYNTAX_OCTET_STRING         "1.3.6.1.4.1.1466.115.121.1.40"
 503
 504 /**
 505   LDAP attribute syntax for UTC time.
 506
 507   This is the well-known LDAP attribute syntax for a UTC time.
 508
 509   See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
 510 */
 511 #define LDB_SYNTAX_UTC_TIME             "1.3.6.1.4.1.1466.115.121.1.53"
 512 #define LDB_SYNTAX_GENERALIZED_TIME     "1.3.6.1.4.1.1466.115.121.1.24"
 513
 514 #define LDB_SYNTAX_OBJECTCLASS          "LDB_SYNTAX_OBJECTCLASS"
 515
 516 /* sorting helpers */
 517 typedef int (*ldb_qsort_cmp_fn_t) (void *v1, void *v2, void *opaque);
 518
 519 /* Individual controls */
 520
 521 /**
 522   OID for getting and manipulating attributes from the ldb
 523   without interception in the operational module.
 524   It can be used to access attribute that used to be stored in the sam
 525   and that are now calculated.
 526 */
 527 #define LDB_CONTROL_BYPASS_OPERATIONAL_OID "1.3.6.1.4.1.7165.4.3.13"
 528 #define LDB_CONTROL_BYPASS_OPERATIONAL_NAME "bypassoperational"
 529
 530 /**
 531   OID for recalculate RDN (rdn attribute and 'name') control. This control forces
 532   the rdn_name module to the recalculate the rdn and name attributes as if the
 533   object was just created.
 534 */
 535 #define LDB_CONTROL_RECALCULATE_RDN_OID "1.3.6.1.4.1.7165.4.3.30"
 536
 537 /**
 538   OID for recalculate SD control. This control force the
 539   dsdb code to recalculate the SD of the object as if the
 540   object was just created.
 541
 542 */
 543 #define LDB_CONTROL_RECALCULATE_SD_OID "1.3.6.1.4.1.7165.4.3.5"
 544 #define LDB_CONTROL_RECALCULATE_SD_NAME "recalculate_sd"
 545
 546 /**
 547    REVEAL_INTERNALS is used to reveal internal attributes and DN
 548    components which are not normally shown to the user
 549 */
 550 #define LDB_CONTROL_REVEAL_INTERNALS "1.3.6.1.4.1.7165.4.3.6"
 551 #define LDB_CONTROL_REVEAL_INTERNALS_NAME       "reveal_internals"
 552
 553 /**
 554    LDB_CONTROL_AS_SYSTEM is used to skip access checks on operations
 555    that are performed by the system, but with a user's credentials, e.g.
 556    updating prefix map
 557 */
 558 #define LDB_CONTROL_AS_SYSTEM_OID "1.3.6.1.4.1.7165.4.3.7"
 559
 560 /**
 561    LDB_CONTROL_PROVISION_OID is used to skip some constraint checks. It's is
 562    mainly thought to be used for the provisioning.
 563 */
 564 #define LDB_CONTROL_PROVISION_OID "1.3.6.1.4.1.7165.4.3.16"
 565 #define LDB_CONTROL_PROVISION_NAME      "provision"
 566
 567 /* AD controls */
 568
 569 /**
 570    OID for the paged results control. This control is included in the
 571    searchRequest and searchResultDone messages as part of the controls
 572    field of the LDAPMessage, as defined in Section 4.1.12 of
 573    LDAP v3.
 574
 575    \sa <a href="http://www.ietf.org/rfc/rfc2696.txt">RFC 2696</a>.
 576 */
 577 #define LDB_CONTROL_PAGED_RESULTS_OID   "1.2.840.113556.1.4.319"
 578 #define LDB_CONTROL_PAGED_RESULTS_NAME  "paged_results"
 579
 580 /**
 581    OID for specifying the returned elements of the ntSecurityDescriptor
 582
 583    \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_sd_flags_oid.asp">Microsoft documentation of this OID</a>
 584 */
 585 #define LDB_CONTROL_SD_FLAGS_OID        "1.2.840.113556.1.4.801"
 586 #define LDB_CONTROL_SD_FLAGS_NAME       "sd_flags"
 587
 588 /**
 589    OID for specifying an advanced scope for the search (one partition)
 590
 591    \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_domain_scope_oid.asp">Microsoft documentation of this OID</a>
 592 */
 593 #define LDB_CONTROL_DOMAIN_SCOPE_OID    "1.2.840.113556.1.4.1339"
 594 #define LDB_CONTROL_DOMAIN_SCOPE_NAME   "domain_scope"
 595
 596 /**
 597    OID for specifying an advanced scope for a search
 598
 599    \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_search_options_oid.asp">Microsoft documentation of this OID</a>
 600 */
 601 #define LDB_CONTROL_SEARCH_OPTIONS_OID  "1.2.840.113556.1.4.1340"
 602 #define LDB_CONTROL_SEARCH_OPTIONS_NAME "search_options"
 603
 604 /**
 605    OID for notification
 606
 607    \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>
 608 */
 609 #define LDB_CONTROL_NOTIFICATION_OID    "1.2.840.113556.1.4.528"
 610 #define LDB_CONTROL_NOTIFICATION_NAME   "notification"
 611
 612 /**
 613    OID for performing subtree deletes
 614
 615    \sa <a href="http://msdn.microsoft.com/en-us/library/aa366991(v=VS.85).aspx">Microsoft documentation of this OID</a>
 616 */
 617 #define LDB_CONTROL_TREE_DELETE_OID     "1.2.840.113556.1.4.805"
 618 #define LDB_CONTROL_TREE_DELETE_NAME    "tree_delete"
 619
 620 /**
 621    OID for getting deleted objects
 622
 623    \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_show_deleted_oid.asp">Microsoft documentation of this OID</a>
 624 */
 625 #define LDB_CONTROL_SHOW_DELETED_OID    "1.2.840.113556.1.4.417"
 626 #define LDB_CONTROL_SHOW_DELETED_NAME   "show_deleted"
 627
 628 /**
 629    OID for getting recycled objects
 630
 631    \sa <a href="http://msdn.microsoft.com/en-us/library/dd304621(PROT.13).aspx">Microsoft documentation of this OID</a>
 632 */
 633 #define LDB_CONTROL_SHOW_RECYCLED_OID         "1.2.840.113556.1.4.2064"
 634 #define LDB_CONTROL_SHOW_RECYCLED_NAME  "show_recycled"
 635
 636 /**
 637    OID for getting deactivated linked attributes
 638
 639    \sa <a href="http://msdn.microsoft.com/en-us/library/dd302781(PROT.13).aspx">Microsoft documentation of this OID</a>
 640 */
 641 #define LDB_CONTROL_SHOW_DEACTIVATED_LINK_OID "1.2.840.113556.1.4.2065"
 642 #define LDB_CONTROL_SHOW_DEACTIVATED_LINK_NAME  "show_deactivated_link"
 643
 644 /**
 645    OID for extended DN
 646
 647    \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>
 648 */
 649 #define LDB_CONTROL_EXTENDED_DN_OID     "1.2.840.113556.1.4.529"
 650 #define LDB_CONTROL_EXTENDED_DN_NAME    "extended_dn"
 651
 652 /**
 653    OID for LDAP server sort result extension.
 654
 655    This control is included in the searchRequest message as part of
 656    the controls field of the LDAPMessage, as defined in Section 4.1.12
 657    of LDAP v3. The controlType is set to
 658    "1.2.840.113556.1.4.473". The criticality MAY be either TRUE or
 659    FALSE (where absent is also equivalent to FALSE) at the client's
 660    option.
 661
 662    \sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
 663 */
 664 #define LDB_CONTROL_SERVER_SORT_OID     "1.2.840.113556.1.4.473"
 665 #define LDB_CONTROL_SERVER_SORT_NAME    "server_sort"
 666
 667 /**
 668    OID for LDAP server sort result response extension.
 669
 670    This control is included in the searchResultDone message as part of
 671    the controls field of the LDAPMessage, as defined in Section 4.1.12 of
 672    LDAP v3.
 673
 674    \sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
 675 */
 676 #define LDB_CONTROL_SORT_RESP_OID       "1.2.840.113556.1.4.474"
 677 #define LDB_CONTROL_SORT_RESP_NAME      "server_sort_resp"
 678
 679 /**
 680    OID for LDAP Attribute Scoped Query extension.
 681
 682    This control is included in SearchRequest or SearchResponse
 683    messages as part of the controls field of the LDAPMessage.
 684 */
 685 #define LDB_CONTROL_ASQ_OID             "1.2.840.113556.1.4.1504"
 686 #define LDB_CONTROL_ASQ_NAME    "asq"
 687
 688 /**
 689    OID for LDAP Directory Sync extension.
 690
 691    This control is included in SearchRequest or SearchResponse
 692    messages as part of the controls field of the LDAPMessage.
 693 */
 694 #define LDB_CONTROL_DIRSYNC_OID         "1.2.840.113556.1.4.841"
 695 #define LDB_CONTROL_DIRSYNC_NAME        "dirsync"
 696 #define LDB_CONTROL_DIRSYNC_EX_OID      "1.2.840.113556.1.4.2090"
 697 #define LDB_CONTROL_DIRSYNC_EX_NAME     "dirsync_ex"
 698
 699
 700 /**
 701    OID for LDAP Virtual List View Request extension.
 702
 703    This control is included in SearchRequest messages
 704    as part of the controls field of the LDAPMessage.
 705 */
 706 #define LDB_CONTROL_VLV_REQ_OID         "2.16.840.1.113730.3.4.9"
 707 #define LDB_CONTROL_VLV_REQ_NAME        "vlv"
 708
 709 /**
 710    OID for LDAP Virtual List View Response extension.
 711
 712    This control is included in SearchResponse messages
 713    as part of the controls field of the LDAPMessage.
 714 */
 715 #define LDB_CONTROL_VLV_RESP_OID        "2.16.840.1.113730.3.4.10"
 716 #define LDB_CONTROL_VLV_RESP_NAME       "vlv_resp"
 717
 718 /**
 719    OID to let modifies don't give an error when adding an existing
 720    attribute with the same value or deleting an nonexisting one attribute
 721
 722    \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_permissive_modify_oid.asp">Microsoft documentation of this OID</a>
 723 */
 724 #define LDB_CONTROL_PERMISSIVE_MODIFY_OID       "1.2.840.113556.1.4.1413"
 725 #define LDB_CONTROL_PERMISSIVE_MODIFY_NAME      "permissive_modify"
 726
 727 /**
 728     OID to allow the server to be more 'fast and loose' with the data being added.
 729
 730     \sa <a href="http://msdn.microsoft.com/en-us/library/aa366982(v=VS.85).aspx">Microsoft documentation of this OID</a>
 731 */
 732 #define LDB_CONTROL_SERVER_LAZY_COMMIT   "1.2.840.113556.1.4.619"
 733
 734 /**
 735    Control for RODC join -see [MS-ADTS] section 3.1.1.3.4.1.23
 736
 737    \sa <a href="">Microsoft documentation of this OID</a>
 738 */
 739 #define LDB_CONTROL_RODC_DCPROMO_OID "1.2.840.113556.1.4.1341"
 740 #define LDB_CONTROL_RODC_DCPROMO_NAME   "rodc_join"
 741
 742 /* Other standardised controls */
 743
 744 /**
 745    OID for the allowing client to request temporary relaxed
 746    enforcement of constraints of the x.500 model.
 747
 748    Mainly used for the OpenLDAP backend.
 749
 750    \sa <a href="http://opends.dev.java.net/public/standards/draft-zeilenga-ldap-managedit.txt">draft managedit</a>.
 751 */
 752 #define LDB_CONTROL_RELAX_OID "1.3.6.1.4.1.4203.666.5.12"
 753 #define LDB_CONTROL_RELAX_NAME  "relax"
 754
 755 /**
 756    OID for the allowing some kind of relax check for attributes with DNs
 757
 758
 759    \sa 3.1.1.3.4.1.16 in [MS-ADTS].pdf
 760 */
 761 #define LDB_CONTROL_VERIFY_NAME_OID "1.2.840.113556.1.4.1338"
 762 #define LDB_CONTROL_VERIFY_NAME_NAME    "verify_name"
 763
 764 /* Extended operations */
 765
 766 /**
 767    OID for LDAP Extended Operation SEQUENCE_NUMBER
 768
 769    This extended operation is used to retrieve the extended sequence number.
 770 */
 771 #define LDB_EXTENDED_SEQUENCE_NUMBER    "1.3.6.1.4.1.7165.4.4.3"
 772
 773 /**
 774    OID for LDAP Extended Operation PASSWORD_CHANGE.
 775
 776    This Extended operation is used to allow user password changes by the user
 777    itself.
 778 */
 779 #define LDB_EXTENDED_PASSWORD_CHANGE_OID        "1.3.6.1.4.1.4203.1.11.1"
 780
 781
 782 /**
 783    OID for LDAP Extended Operation FAST_BIND
 784
 785    This Extended operations is used to perform a fast bind.
 786 */
 787 #define LDB_EXTENDED_FAST_BIND_OID      "1.2.840.113556.1.4.1781"
 788
 789 /**
 790    OID for LDAP Extended Operation START_TLS.
 791
 792    This Extended operation is used to start a new TLS channel on top of a clear
 793    text channel.
 794 */
 795 #define LDB_EXTENDED_START_TLS_OID      "1.3.6.1.4.1.1466.20037"
 796
 797 /**
 798    OID for LDAP Extended Operation DYNAMIC_REFRESH.
 799
 800    This Extended operation is used to create and maintain objects which exist
 801    only a specific time, e.g. when a certain client or a certain person is
 802    logged in. Data refreshes have to be periodically sent in a specific
 803    interval. Otherwise the entry is going to be removed.
 804 */
 805 #define LDB_EXTENDED_DYNAMIC_OID        "1.3.6.1.4.1.1466.101.119.1"
 806
 807 struct ldb_sd_flags_control {
 808         /*
 809          * request the owner    0x00000001
 810          * request the group    0x00000002
 811          * request the DACL     0x00000004
 812          * request the SACL     0x00000008
 813          */
 814         unsigned secinfo_flags;
 815 };
 816
 817 /*
 818  * DOMAIN_SCOPE         0x00000001
 819  * this limits the search to one partition,
 820  * and no referrals will be returned.
 821  * (Note this doesn't limit the entries by there
 822  *  objectSid belonging to a domain! Builtin and Foreign Sids
 823  *  are still returned)
 824  *
 825  * PHANTOM_ROOT         0x00000002
 826  * this search on the whole tree on a domain controller
 827  * over multiple partitions without referrals.
 828  * (This is the default behavior on the Global Catalog Port)
 829  */
 830
 831 #define LDB_SEARCH_OPTION_DOMAIN_SCOPE 0x00000001
 832 #define LDB_SEARCH_OPTION_PHANTOM_ROOT 0x00000002
 833
 834 struct ldb_search_options_control {
 835         unsigned search_options;
 836 };
 837
 838 struct ldb_paged_control {
 839         int size;
 840         int cookie_len;
 841         char *cookie;
 842 };
 843
 844 struct ldb_extended_dn_control {
 845         int type;
 846 };
 847
 848 struct ldb_server_sort_control {
 849         const char *attributeName;
 850         const char *orderingRule;
 851         int reverse;
 852 };
 853
 854 struct ldb_sort_resp_control {
 855         int result;
 856         char *attr_desc;
 857 };
 858
 859 struct ldb_asq_control {
 860         int request;
 861         char *source_attribute;
 862         int src_attr_len;
 863         int result;
 864 };
 865
 866 struct ldb_dirsync_control {
 867         int flags;
 868         int max_attributes;
 869         int cookie_len;
 870         char *cookie;
 871 };
 872
 873 struct ldb_vlv_req_control {
 874         int beforeCount;
 875         int afterCount;
 876         int type;
 877         union {
 878                 struct {
 879                         int offset;
 880                         int contentCount;
 881                 } byOffset;
 882                 struct {
 883                         int value_len;
 884                         char *value;
 885                 } gtOrEq;
 886         } match;
 887         int ctxid_len;
 888         uint8_t *contextId;
 889 };
 890
 891 struct ldb_vlv_resp_control {
 892         int targetPosition;
 893         int contentCount;
 894         int vlv_result;
 895         int ctxid_len;
 896         uint8_t *contextId;
 897 };
 898
 899 struct ldb_verify_name_control {
 900         int flags;
 901         size_t gc_len;
 902         char *gc;
 903 };
 904
 905 struct ldb_control {
 906         const char *oid;
 907         int critical;
 908         void *data;
 909 };
 910
 911 enum ldb_request_type {
 912         LDB_SEARCH,
 913         LDB_ADD,
 914         LDB_MODIFY,
 915         LDB_DELETE,
 916         LDB_RENAME,
 917         LDB_EXTENDED,
 918         LDB_REQ_REGISTER_CONTROL,
 919         LDB_REQ_REGISTER_PARTITION
 920 };
 921
 922 enum ldb_reply_type {
 923         LDB_REPLY_ENTRY,
 924         LDB_REPLY_REFERRAL,
 925         LDB_REPLY_DONE
 926 };
 927
 928 enum ldb_wait_type {
 929         LDB_WAIT_ALL,
 930         LDB_WAIT_NONE
 931 };
 932
 933 enum ldb_state {
 934         LDB_ASYNC_INIT,
 935         LDB_ASYNC_PENDING,
 936         LDB_ASYNC_DONE
 937 };
 938
 939 struct ldb_extended {
 940         const char *oid;
 941         void *data; /* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
 942 };
 943
 944 enum ldb_sequence_type {
 945         LDB_SEQ_HIGHEST_SEQ,
 946         LDB_SEQ_HIGHEST_TIMESTAMP,
 947         LDB_SEQ_NEXT
 948 };
 949
 950 #define LDB_SEQ_GLOBAL_SEQUENCE    0x01
 951 #define LDB_SEQ_TIMESTAMP_SEQUENCE 0x02
 952
 953 struct ldb_seqnum_request {
 954         enum ldb_sequence_type type;
 955 };
 956
 957 struct ldb_seqnum_result {
 958         uint64_t seq_num;
 959         uint32_t flags;
 960 };
 961
 962 struct ldb_result {
 963         unsigned int count;
 964         struct ldb_message **msgs;
 965         struct ldb_extended *extended;
 966         struct ldb_control **controls;
 967         char **refs;
 968 };
 969
 970 struct ldb_reply {
 971         int error;
 972         enum ldb_reply_type type;
 973         struct ldb_message *message;
 974         struct ldb_extended *response;
 975         struct ldb_control **controls;
 976         char *referral;
 977 };
 978
 979 struct ldb_request;
 980 struct ldb_handle;
 981
 982 struct ldb_search {
 983         struct ldb_dn *base;
 984         enum ldb_scope scope;
 985         struct ldb_parse_tree *tree;
 986         const char * const *attrs;
 987         struct ldb_result *res;
 988 };
 989
 990 struct ldb_add {
 991         const struct ldb_message *message;
 992 };
 993
 994 struct ldb_modify {
 995         const struct ldb_message *message;
 996 };
 997
 998 struct ldb_delete {
 999         struct ldb_dn *dn;
1000 };
1001
1002 struct ldb_rename {
1003         struct ldb_dn *olddn;
1004         struct ldb_dn *newdn;
1005 };
1006
1007 struct ldb_register_control {
1008         const char *oid;
1009 };
1010
1011 struct ldb_register_partition {
1012         struct ldb_dn *dn;
1013 };
1014
1015 typedef int (*ldb_request_callback_t)(struct ldb_request *, struct ldb_reply *);
1016
1017 struct ldb_request {
1018
1019         enum ldb_request_type operation;
1020
1021         union {
1022                 struct ldb_search search;
1023                 struct ldb_add    add;
1024                 struct ldb_modify mod;
1025                 struct ldb_delete del;
1026                 struct ldb_rename rename;
1027                 struct ldb_extended extended;
1028                 struct ldb_register_control reg_control;
1029                 struct ldb_register_partition reg_partition;
1030         } op;
1031
1032         struct ldb_control **controls;
1033
1034         void *context;
1035         ldb_request_callback_t callback;
1036
1037         int timeout;
1038         time_t starttime;
1039         struct ldb_handle *handle;
1040 };
1041
1042 int ldb_request(struct ldb_context *ldb, struct ldb_request *request);
1043 int ldb_request_done(struct ldb_request *req, int status);
1044 bool ldb_request_is_done(struct ldb_request *req);
1045
1046 int ldb_modules_wait(struct ldb_handle *handle);
1047 int ldb_wait(struct ldb_handle *handle, enum ldb_wait_type type);
1048
1049 int ldb_set_timeout(struct ldb_context *ldb, struct ldb_request *req, int timeout);
1050 int ldb_set_timeout_from_prev_req(struct ldb_context *ldb, struct ldb_request *oldreq, struct ldb_request *newreq);
1051 void ldb_set_create_perms(struct ldb_context *ldb, unsigned int perms);
1052 void ldb_set_modules_dir(struct ldb_context *ldb, const char *path);
1053 struct tevent_context;
1054 void ldb_set_event_context(struct ldb_context *ldb, struct tevent_context *ev);
1055 struct tevent_context * ldb_get_event_context(struct ldb_context *ldb);
1056
1057 /**
1058   Initialise ldbs' global information
1059
1060   This is required before any other LDB call
1061
1062   \return 0 if initialisation succeeded, -1 otherwise
1063 */
1064 int ldb_global_init(void);
1065
1066 /**
1067   Initialise an ldb context
1068
1069   This is required before any other LDB call.
1070
1071   \param mem_ctx pointer to a talloc memory context. Pass NULL if there is
1072   no suitable context available.
1073
1074   \note The LDB modules will be loaded from directory specified by the environment
1075   variable LDB_MODULES_PATH. If the variable is not specified, the compiled-in default
1076   is used.
1077
1078   \return pointer to ldb_context that should be free'd (using talloc_free())
1079   at the end of the program.
1080 */
1081 struct ldb_context *ldb_init(TALLOC_CTX *mem_ctx, struct tevent_context *ev_ctx);
1082
1083 typedef void (*ldb_async_timeout_fn) (void *);
1084 typedef bool (*ldb_async_callback_fn) (void *);
1085 typedef int (*ldb_async_ctx_add_op_fn)(void *, time_t, void *, ldb_async_timeout_fn, ldb_async_callback_fn);
1086 typedef int (*ldb_async_ctx_wait_op_fn)(void *);
1087
1088 void ldb_async_ctx_set_private_data(struct ldb_context *ldb,
1089                                         void *private_data);
1090 void ldb_async_ctx_set_add_op(struct ldb_context *ldb,
1091                                 ldb_async_ctx_add_op_fn add_op);
1092 void ldb_async_ctx_set_wait_op(struct ldb_context *ldb,
1093                                 ldb_async_ctx_wait_op_fn wait_op);
1094
1095 /**
1096    Connect to a database.
1097
1098    This is typically called soon after ldb_init(), and is required prior to
1099    any search or database modification operations.
1100
1101    The URL can be one of the following forms:
1102     - tdb://path
1103     - ldapi://path
1104     - ldap://host
1105     - sqlite://path
1106
1107    \param ldb the context associated with the database (from ldb_init())
1108    \param url the URL of the database to connect to, as noted above
1109    \param flags a combination of LDB_FLG_* to modify the connection behaviour
1110    \param options backend specific options - passed uninterpreted to the backend
1111
1112    \return result code (LDB_SUCCESS on success, or a failure code)
1113
1114    \note It is an error to connect to a database that does not exist in readonly mode
1115    (that is, with LDB_FLG_RDONLY). However in read-write mode, the database will be
1116    created if it does not exist.
1117 */
1118 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
1119
1120 /*
1121   return an automatic basedn from the rootDomainNamingContext of the rootDSE
1122   This value have been set in an opaque pointer at connection time
1123 */
1124 struct ldb_dn *ldb_get_root_basedn(struct ldb_context *ldb);
1125
1126 /*
1127   return an automatic basedn from the configurationNamingContext of the rootDSE
1128   This value have been set in an opaque pointer at connection time
1129 */
1130 struct ldb_dn *ldb_get_config_basedn(struct ldb_context *ldb);
1131
1132 /*
1133   return an automatic basedn from the schemaNamingContext of the rootDSE
1134   This value have been set in an opaque pointer at connection time
1135 */
1136 struct ldb_dn *ldb_get_schema_basedn(struct ldb_context *ldb);
1137
1138 /*
1139   return an automatic baseDN from the defaultNamingContext of the rootDSE
1140   This value have been set in an opaque pointer at connection time
1141 */
1142 struct ldb_dn *ldb_get_default_basedn(struct ldb_context *ldb);
1143
1144 /**
1145   The default async search callback function
1146
1147   \param req the request we are callback of
1148   \param ares a single reply from the async core
1149
1150   \return result code (LDB_SUCCESS on success, or a failure code)
1151
1152   \note this function expects req->context to always be an struct ldb_result pointer
1153   AND a talloc context, this function will steal on the context each message
1154   from the ares reply passed on by the async core so that in the end all the
1155   messages will be in the context (ldb_result)  memory tree.
1156   Freeing the passed context (ldb_result tree) will free all the resources
1157   (the request need to be freed separately and the result doe not depend on the
1158   request that can be freed as sson as the search request is finished)
1159 */
1160
1161 int ldb_search_default_callback(struct ldb_request *req, struct ldb_reply *ares);
1162
1163 /**
1164   The default async extended operation callback function
1165
1166   \param req the request we are callback of
1167   \param ares a single reply from the async core
1168
1169   \return result code (LDB_SUCCESS on success, or a failure code)
1170 */
1171 int ldb_op_default_callback(struct ldb_request *req, struct ldb_reply *ares);
1172
1173 int ldb_modify_default_callback(struct ldb_request *req, struct ldb_reply *ares);
1174
1175 /**
1176   Helper function to build a search request
1177
1178   \param ret_req the request structure is returned here (talloced on mem_ctx)
1179   \param ldb the context associated with the database (from ldb_init())
1180   \param mem_ctx a talloc memory context (used as parent of ret_req)
1181   \param base the Base Distinguished Name for the query (use ldb_dn_new() for an empty one)
1182   \param scope the search scope for the query
1183   \param expression the search expression to use for this query
1184   \param attrs the search attributes for the query (pass NULL if none required)
1185   \param controls an array of controls
1186   \param context the callback function context
1187   \param the callback function to handle the async replies
1188   \param the parent request if any
1189
1190   \return result code (LDB_SUCCESS on success, or a failure code)
1191 */
1192
1193 int ldb_build_search_req(struct ldb_request **ret_req,
1194                         struct ldb_context *ldb,
1195                         TALLOC_CTX *mem_ctx,
1196                         struct ldb_dn *base,
1197                         enum ldb_scope scope,
1198                         const char *expression,
1199                         const char * const *attrs,
1200                         struct ldb_control **controls,
1201                         void *context,
1202                         ldb_request_callback_t callback,
1203                         struct ldb_request *parent);
1204
1205 int ldb_build_search_req_ex(struct ldb_request **ret_req,
1206                         struct ldb_context *ldb,
1207                         TALLOC_CTX *mem_ctx,
1208                         struct ldb_dn *base,
1209                         enum ldb_scope scope,
1210                         struct ldb_parse_tree *tree,
1211                         const char * const *attrs,
1212                         struct ldb_control **controls,
1213                         void *context,
1214                         ldb_request_callback_t callback,
1215                         struct ldb_request *parent);
1216
1217 /**
1218   Helper function to build an add request
1219
1220   \param ret_req the request structure is returned here (talloced on mem_ctx)
1221   \param ldb the context associated with the database (from ldb_init())
1222   \param mem_ctx a talloc memory context (used as parent of ret_req)
1223   \param message contains the entry to be added
1224   \param controls an array of controls
1225   \param context the callback function context
1226   \param the callback function to handle the async replies
1227   \param the parent request if any
1228
1229   \return result code (LDB_SUCCESS on success, or a failure code)
1230 */
1231
1232 int ldb_build_add_req(struct ldb_request **ret_req,
1233                         struct ldb_context *ldb,
1234                         TALLOC_CTX *mem_ctx,
1235                         const struct ldb_message *message,
1236                         struct ldb_control **controls,
1237                         void *context,
1238                         ldb_request_callback_t callback,
1239                         struct ldb_request *parent);
1240
1241 /**
1242   Helper function to build a modify request
1243
1244   \param ret_req the request structure is returned here (talloced on mem_ctx)
1245   \param ldb the context associated with the database (from ldb_init())
1246   \param mem_ctx a talloc memory context (used as parent of ret_req)
1247   \param message contains the entry to be modified
1248   \param controls an array of controls
1249   \param context the callback function context
1250   \param the callback function to handle the async replies
1251   \param the parent request if any
1252
1253   \return result code (LDB_SUCCESS on success, or a failure code)
1254 */
1255
1256 int ldb_build_mod_req(struct ldb_request **ret_req,
1257                         struct ldb_context *ldb,
1258                         TALLOC_CTX *mem_ctx,
1259                         const struct ldb_message *message,
1260                         struct ldb_control **controls,
1261                         void *context,
1262                         ldb_request_callback_t callback,
1263                         struct ldb_request *parent);
1264
1265 /**
1266   Helper function to build a delete request
1267
1268   \param ret_req the request structure is returned here (talloced on mem_ctx)
1269   \param ldb the context associated with the database (from ldb_init())
1270   \param mem_ctx a talloc memory context (used as parent of ret_req)
1271   \param dn the DN to be deleted
1272   \param controls an array of controls
1273   \param context the callback function context
1274   \param the callback function to handle the async replies
1275   \param the parent request if any
1276
1277   \return result code (LDB_SUCCESS on success, or a failure code)
1278 */
1279
1280 int ldb_build_del_req(struct ldb_request **ret_req,
1281                         struct ldb_context *ldb,
1282                         TALLOC_CTX *mem_ctx,
1283                         struct ldb_dn *dn,
1284                         struct ldb_control **controls,
1285                         void *context,
1286                         ldb_request_callback_t callback,
1287                         struct ldb_request *parent);
1288
1289 /**
1290   Helper function to build a rename request
1291
1292   \param ret_req the request structure is returned here (talloced on mem_ctx)
1293   \param ldb the context associated with the database (from ldb_init())
1294   \param mem_ctx a talloc memory context (used as parent of ret_req)
1295   \param olddn the old DN
1296   \param newdn the new DN
1297   \param controls an array of controls
1298   \param context the callback function context
1299   \param the callback function to handle the async replies
1300   \param the parent request if any
1301
1302   \return result code (LDB_SUCCESS on success, or a failure code)
1303 */
1304
1305 int ldb_build_rename_req(struct ldb_request **ret_req,
1306                         struct ldb_context *ldb,
1307                         TALLOC_CTX *mem_ctx,
1308                         struct ldb_dn *olddn,
1309                         struct ldb_dn *newdn,
1310                         struct ldb_control **controls,
1311                         void *context,
1312                         ldb_request_callback_t callback,
1313                         struct ldb_request *parent);
1314
1315 /**
1316   Add a ldb_control to a ldb_request
1317
1318   \param req the request struct where to add the control
1319   \param oid the object identifier of the control as string
1320   \param critical whether the control should be critical or not
1321   \param data a talloc pointer to the control specific data
1322
1323   \return result code (LDB_SUCCESS on success, or a failure code)
1324 */
1325 int ldb_request_add_control(struct ldb_request *req, const char *oid, bool critical, void *data);
1326
1327 /**
1328   replace a ldb_control in a ldb_request
1329
1330   \param req the request struct where to add the control
1331   \param oid the object identifier of the control as string
1332   \param critical whether the control should be critical or not
1333   \param data a talloc pointer to the control specific data
1334
1335   \return result code (LDB_SUCCESS on success, or a failure code)
1336 */
1337 int ldb_request_replace_control(struct ldb_request *req, const char *oid, bool critical, void *data);
1338
1339 /**
1340    check if a control with the specified "oid" exist and return it
1341   \param req the request struct where to add the control
1342   \param oid the object identifier of the control as string
1343
1344   \return the control, NULL if not found
1345 */
1346 struct ldb_control *ldb_request_get_control(struct ldb_request *req, const char *oid);
1347
1348 /**
1349    check if a control with the specified "oid" exist and return it
1350   \param rep the reply struct where to add the control
1351   \param oid the object identifier of the control as string
1352
1353   \return the control, NULL if not found
1354 */
1355 struct ldb_control *ldb_reply_get_control(struct ldb_reply *rep, const char *oid);
1356
1357 /**
1358   Search the database
1359
1360   This function searches the database, and returns
1361   records that match an LDAP-like search expression
1362
1363   \param ldb the context associated with the database (from ldb_init())
1364   \param mem_ctx the memory context to use for the request and the results
1365   \param result the return result
1366   \param base the Base Distinguished Name for the query (use ldb_dn_new() for an empty one)
1367   \param scope the search scope for the query
1368   \param attrs the search attributes for the query (pass NULL if none required)
1369   \param exp_fmt the search expression to use for this query (printf like)
1370
1371   \return result code (LDB_SUCCESS on success, or a failure code)
1372
1373   \note use talloc_free() to free the ldb_result returned
1374 */
1375 int ldb_search(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
1376                struct ldb_result **result, struct ldb_dn *base,
1377                enum ldb_scope scope, const char * const *attrs,
1378                const char *exp_fmt, ...) PRINTF_ATTRIBUTE(7,8);
1379
1380 /**
1381   Add a record to the database.
1382
1383   This function adds a record to the database. This function will fail
1384   if a record with the specified class and key already exists in the
1385   database.
1386
1387   \param ldb the context associated with the database (from
1388   ldb_init())
1389   \param message the message containing the record to add.
1390
1391   \return result code (LDB_SUCCESS if the record was added, otherwise
1392   a failure code)
1393 */
1394 int ldb_add(struct ldb_context *ldb,
1395             const struct ldb_message *message);
1396
1397 /**
1398   Modify the specified attributes of a record
1399
1400   This function modifies a record that is in the database.
1401
1402   \param ldb the context associated with the database (from
1403   ldb_init())
1404   \param message the message containing the changes required.
1405
1406   \return result code (LDB_SUCCESS if the record was modified as
1407   requested, otherwise a failure code)
1408 */
1409 int ldb_modify(struct ldb_context *ldb,
1410                const struct ldb_message *message);
1411
1412 /**
1413   Rename a record in the database
1414
1415   This function renames a record in the database.
1416
1417   \param ldb the context associated with the database (from
1418   ldb_init())
1419   \param olddn the DN for the record to be renamed.
1420   \param newdn the new DN
1421
1422   \return result code (LDB_SUCCESS if the record was renamed as
1423   requested, otherwise a failure code)
1424 */
1425 int ldb_rename(struct ldb_context *ldb, struct ldb_dn *olddn, struct ldb_dn *newdn);
1426
1427 /**
1428   Delete a record from the database
1429
1430   This function deletes a record from the database.
1431
1432   \param ldb the context associated with the database (from
1433   ldb_init())
1434   \param dn the DN for the record to be deleted.
1435
1436   \return result code (LDB_SUCCESS if the record was deleted,
1437   otherwise a failure code)
1438 */
1439 int ldb_delete(struct ldb_context *ldb, struct ldb_dn *dn);
1440
1441 /**
1442   The default async extended operation callback function
1443
1444   \param req the request we are callback of
1445   \param ares a single reply from the async core
1446
1447   \return result code (LDB_SUCCESS on success, or a failure code)
1448
1449   \note this function expects req->context to always be an struct ldb_result pointer
1450   AND a talloc context, this function will steal on the context each message
1451   from the ares reply passed on by the async core so that in the end all the
1452   messages will be in the context (ldb_result)  memory tree.
1453   Freeing the passed context (ldb_result tree) will free all the resources
1454   (the request need to be freed separately and the result doe not depend on the
1455   request that can be freed as sson as the search request is finished)
1456 */
1457
1458 int ldb_extended_default_callback(struct ldb_request *req, struct ldb_reply *ares);
1459
1460
1461 /**
1462   Helper function to build a extended request
1463
1464   \param ret_req the request structure is returned here (talloced on mem_ctx)
1465   \param ldb the context associated with the database (from ldb_init())
1466   \param mem_ctx a talloc memory context (used as parent of ret_req)
1467   \param oid the OID of the extended operation.
1468   \param data a void pointer a the extended operation specific parameters,
1469   it needs to be NULL or a valid talloc pointer! talloc_get_type() will be used on it
1470   \param controls an array of controls
1471   \param context the callback function context
1472   \param the callback function to handle the async replies
1473   \param the parent request if any
1474
1475   \return result code (LDB_SUCCESS on success, or a failure code)
1476 */
1477 int ldb_build_extended_req(struct ldb_request **ret_req,
1478                            struct ldb_context *ldb,
1479                            TALLOC_CTX *mem_ctx,
1480                            const char *oid,
1481                            void *data,/* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
1482                            struct ldb_control **controls,
1483                            void *context,
1484                            ldb_request_callback_t callback,
1485                            struct ldb_request *parent);
1486
1487 /**
1488   call an extended operation
1489
1490   \param ldb the context associated with the database (from ldb_init())
1491   \param oid the OID of the extended operation.
1492   \param data a void pointer a the extended operation specific parameters,
1493   it needs to be NULL or a valid talloc pointer! talloc_get_type() will be used on it
1494   \param res the result of the extended operation
1495
1496   \return result code (LDB_SUCCESS if the extended operation returned fine,
1497   otherwise a failure code)
1498 */
1499 int ldb_extended(struct ldb_context *ldb,
1500                  const char *oid,
1501                  void *data,/* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
1502                  struct ldb_result **res);
1503
1504 /**
1505   Obtain current/next database sequence number
1506 */
1507 int ldb_sequence_number(struct ldb_context *ldb, enum ldb_sequence_type type, uint64_t *seq_num);
1508
1509 /**
1510   start a transaction
1511 */
1512 int ldb_transaction_start(struct ldb_context *ldb);
1513
1514 /**
1515    first phase of two phase commit
1516  */
1517 int ldb_transaction_prepare_commit(struct ldb_context *ldb);
1518
1519 /**
1520   commit a transaction
1521 */
1522 int ldb_transaction_commit(struct ldb_context *ldb);
1523
1524 /**
1525   cancel a transaction
1526 */
1527 int ldb_transaction_cancel(struct ldb_context *ldb);
1528
1529 /*
1530   cancel a transaction with no error if no transaction is pending
1531   used when we fork() to clear any parent transactions
1532 */
1533 int ldb_transaction_cancel_noerr(struct ldb_context *ldb);
1534
1535
1536 /**
1537   return extended error information from the last call
1538 */
1539 const char *ldb_errstring(struct ldb_context *ldb);
1540
1541 /**
1542   return a string explaining what a ldb error constant meancs
1543 */
1544 const char *ldb_strerror(int ldb_err);
1545
1546 /**
1547   setup the default utf8 functions
1548   FIXME: these functions do not yet handle utf8
1549 */
1550 void ldb_set_utf8_default(struct ldb_context *ldb);
1551
1552 /**
1553    Casefold a string
1554
1555    \param ldb the ldb context
1556    \param mem_ctx the memory context to allocate the result string
1557    memory from.
1558    \param s the string that is to be folded
1559    \return a copy of the string, converted to upper case
1560
1561    \note The default function is not yet UTF8 aware. Provide your own
1562          set of functions through ldb_set_utf8_fns()
1563 */
1564 char *ldb_casefold(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *s, size_t n);
1565
1566 /**
1567    Check the attribute name is valid according to rfc2251
1568    \param s the string to check
1569
1570    \return 1 if the name is ok
1571 */
1572 int ldb_valid_attr_name(const char *s);
1573
1574 /*
1575   ldif manipulation functions
1576 */
1577
1578 /**
1579    Write an LDIF message
1580
1581    This function writes an LDIF message using a caller supplied  write
1582    function.
1583
1584    \param ldb the ldb context (from ldb_init())
1585    \param fprintf_fn a function pointer for the write function. This must take
1586    a private data pointer, followed by a format string, and then a variable argument
1587    list.
1588    \param private_data pointer that will be provided back to the write
1589    function. This is useful for maintaining state or context.
1590    \param ldif the message to write out
1591
1592    \return the total number of bytes written, or an error code as returned
1593    from the write function.
1594
1595    \sa ldb_ldif_write_file for a more convenient way to write to a
1596    file stream.
1597
1598    \sa ldb_ldif_read for the reader equivalent to this function.
1599 */
1600 int ldb_ldif_write(struct ldb_context *ldb,
1601                    int (*fprintf_fn)(void *, const char *, ...) PRINTF_ATTRIBUTE(2,3),
1602                    void *private_data,
1603                    const struct ldb_ldif *ldif);
1604
1605 /**
1606    Clean up an LDIF message
1607
1608    This function cleans up a LDIF message read using ldb_ldif_read()
1609    or related functions (such as ldb_ldif_read_string() and
1610    ldb_ldif_read_file().
1611
1612    \param ldb the ldb context (from ldb_init())
1613    \param msg the message to clean up and free
1614
1615 */
1616 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *msg);
1617
1618 /**
1619    Read an LDIF message
1620
1621    This function creates an LDIF message using a caller supplied read
1622    function.
1623
1624    \param ldb the ldb context (from ldb_init())
1625    \param fgetc_fn a function pointer for the read function. This must
1626    take a private data pointer, and must return a pointer to an
1627    integer corresponding to the next byte read (or EOF if there is no
1628    more data to be read).
1629    \param private_data pointer that will be provided back to the read
1630    function. This is udeful for maintaining state or context.
1631
1632    \return the LDIF message that has been read in
1633
1634    \note You must free the LDIF message when no longer required, using
1635    ldb_ldif_read_free().
1636
1637    \sa ldb_ldif_read_file for a more convenient way to read from a
1638    file stream.
1639
1640    \sa ldb_ldif_read_string for a more convenient way to read from a
1641    string (char array).
1642
1643    \sa ldb_ldif_write for the writer equivalent to this function.
1644 */
1645 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
1646                                int (*fgetc_fn)(void *), void *private_data);
1647
1648 /**
1649    Read an LDIF message from a file
1650
1651    This function reads the next LDIF message from the contents of a
1652    file stream. If you want to get all of the LDIF messages, you will
1653    need to repeatedly call this function, until it returns NULL.
1654
1655    \param ldb the ldb context (from ldb_init())
1656    \param f the file stream to read from (typically from fdopen())
1657
1658    \sa ldb_ldif_read_string for an equivalent function that will read
1659    from a string (char array).
1660
1661    \sa ldb_ldif_write_file for the writer equivalent to this function.
1662
1663 */
1664 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
1665
1666 /**
1667    Read an LDIF message from a string
1668
1669    This function reads the next LDIF message from the contents of a char
1670    array. If you want to get all of the LDIF messages, you will need
1671    to repeatedly call this function, until it returns NULL.
1672
1673    \param ldb the ldb context (from ldb_init())
1674    \param s pointer to the char array to read from
1675
1676    \sa ldb_ldif_read_file for an equivalent function that will read
1677    from a file stream.
1678
1679    \sa ldb_ldif_write for a more general (arbitrary read function)
1680    version of this function.
1681 */
1682 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
1683
1684 /**
1685    Parse a modrdn LDIF message from a struct ldb_message
1686
1687    \param ldb the ldb context (from ldb_init())
1688    \param ldif the preparsed LDIF chunk (from ldb_ldif_read())
1689
1690    \param mem_ctx the memory context that's used for return values
1691
1692    \param olddn the old dn as struct ldb_dn, if not needed pass NULL
1693    \param newrdn the new rdn as struct ldb_dn, if not needed pass NULL
1694    \param deleteoldrdn the deleteoldrdn value as bool, if not needed pass NULL
1695    \param newsuperior the newsuperior dn as struct ldb_dn, if not needed pass NULL
1696                       *newsuperior can be NULL as it is optional in the LDIF
1697    \param newdn the full constructed new dn as struct ldb_dn, if not needed pass NULL
1698
1699 */
1700 int ldb_ldif_parse_modrdn(struct ldb_context *ldb,
1701                           const struct ldb_ldif *ldif,
1702                           TALLOC_CTX *mem_ctx,
1703                           struct ldb_dn **olddn,
1704                           struct ldb_dn **newrdn,
1705                           bool *deleteoldrdn,
1706                           struct ldb_dn **newsuperior,
1707                           struct ldb_dn **newdn);
1708
1709 /**
1710    Write an LDIF message to a file
1711
1712    \param ldb the ldb context (from ldb_init())
1713    \param f the file stream to write to (typically from fdopen())
1714    \param msg the message to write out
1715
1716    \return the total number of bytes written, or a negative error code
1717
1718    \sa ldb_ldif_read_file for the reader equivalent to this function.
1719 */
1720 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
1721
1722 /**
1723    Write an LDIF message to a string
1724
1725    \param ldb the ldb context (from ldb_init())
1726    \param mem_ctx the talloc context on which to attach the string)
1727    \param msg the message to write out
1728
1729    \return the string containing the LDIF, or NULL on error
1730
1731    \sa ldb_ldif_read_string for the reader equivalent to this function.
1732 */
1733 char * ldb_ldif_write_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
1734                           const struct ldb_ldif *msg);
1735
1736
1737 /**
1738    Write an LDB message to a string
1739
1740    \param ldb the ldb context (from ldb_init())
1741    \param mem_ctx the talloc context on which to attach the string)
1742    \param changetype LDB_CHANGETYPE_ADD or LDB_CHANGETYPE_MODIFY
1743    \param msg the message to write out
1744
1745    \return the string containing the LDIF, or NULL on error
1746
1747    \sa ldb_ldif_message_redacted_string for a safer version of this
1748        function
1749 */
1750 char *ldb_ldif_message_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
1751                               enum ldb_changetype changetype,
1752                               const struct ldb_message *msg);
1753
1754 /**
1755    Write an LDB message to a string
1756
1757    \param ldb the ldb context (from ldb_init())
1758    \param mem_ctx the talloc context on which to attach the string)
1759    \param changetype LDB_CHANGETYPE_ADD or LDB_CHANGETYPE_MODIFY
1760    \param msg the message to write out
1761
1762    \return the string containing the LDIF, or NULL on error, but
1763            with secret attributes redacted
1764
1765    \note The secret attributes are specified in a
1766          'const char * const *' within the LDB_SECRET_ATTRIBUTE_LIST
1767          opaque set on the ldb
1768
1769    \sa ldb_ldif_message_string for an exact representiation of the
1770        message as LDIF
1771 */
1772 char *ldb_ldif_message_redacted_string(struct ldb_context *ldb,
1773                                        TALLOC_CTX *mem_ctx,
1774                                        enum ldb_changetype changetype,
1775                                        const struct ldb_message *msg);
1776
1777
1778 /**
1779    Base64 encode a buffer
1780
1781    \param mem_ctx the memory context that the result is allocated
1782    from.
1783    \param buf pointer to the array that is to be encoded
1784    \param len the number of elements in the array to be encoded
1785
1786    \return pointer to an array containing the encoded data
1787
1788    \note The caller is responsible for freeing the result
1789 */
1790 char *ldb_base64_encode(TALLOC_CTX *mem_ctx, const char *buf, int len);
1791
1792 /**
1793    Base64 decode a buffer
1794
1795    This function decodes a base64 encoded string in place.
1796
1797    \param s the string to decode.
1798
1799    \return the length of the returned (decoded) string.
1800
1801    \note the string is null terminated, but the null terminator is not
1802    included in the length.
1803 */
1804 int ldb_base64_decode(char *s);
1805
1806 /* The following definitions come from lib/ldb/common/ldb_dn.c  */
1807
1808 /**
1809   Get the linear form of a DN (without any extended components)
1810
1811   \param dn The DN to linearize
1812 */
1813
1814 const char *ldb_dn_get_linearized(struct ldb_dn *dn);
1815
1816 /**
1817   Allocate a copy of the linear form of a DN (without any extended components) onto the supplied memory context
1818
1819   \param dn The DN to linearize
1820   \param mem_ctx TALLOC context to return result on
1821 */
1822
1823 char *ldb_dn_alloc_linearized(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1824
1825 /**
1826   Get the linear form of a DN (with any extended components)
1827
1828   \param mem_ctx TALLOC context to return result on
1829   \param dn The DN to linearize
1830   \param mode Style of extended DN to return (0 is HEX representation of binary form, 1 is a string form)
1831 */
1832 char *ldb_dn_get_extended_linearized(TALLOC_CTX *mem_ctx, struct ldb_dn *dn, int mode);
1833 const struct ldb_val *ldb_dn_get_extended_component(struct ldb_dn *dn, const char *name);
1834 int ldb_dn_set_extended_component(struct ldb_dn *dn, const char *name, const struct ldb_val *val);
1835 void ldb_dn_extended_filter(struct ldb_dn *dn, const char * const *accept_list);
1836 void ldb_dn_remove_extended_components(struct ldb_dn *dn);
1837 bool ldb_dn_has_extended(struct ldb_dn *dn);
1838
1839 int ldb_dn_extended_add_syntax(struct ldb_context *ldb,
1840                                unsigned flags,
1841                                const struct ldb_dn_extended_syntax *syntax);
1842
1843 /**
1844   Allocate a new DN from a string
1845
1846   \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1847   \param dn The new DN
1848
1849   \note The DN will not be parsed at this time.  Use ldb_dn_validate to tell if the DN is syntacticly correct
1850 */
1851
1852 struct ldb_dn *ldb_dn_new(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *dn);
1853 /**
1854   Allocate a new DN from a printf style format string and arguments
1855
1856   \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1857   \param new_fms The new DN as a format string (plus arguments)
1858
1859   \note The DN will not be parsed at this time.  Use ldb_dn_validate to tell if the DN is syntacticly correct
1860 */
1861
1862 struct ldb_dn *ldb_dn_new_fmt(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *new_fmt, ...) PRINTF_ATTRIBUTE(3,4);
1863 /**
1864   Allocate a new DN from a struct ldb_val (useful to avoid buffer overrun)
1865
1866   \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1867   \param dn The new DN
1868
1869   \note The DN will not be parsed at this time.  Use ldb_dn_validate to tell if the DN is syntacticly correct
1870 */
1871
1872 struct ldb_dn *ldb_dn_from_ldb_val(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const struct ldb_val *strdn);
1873
1874 /**
1875   Determine if this DN is syntactically valid
1876
1877   \param dn The DN to validate
1878 */
1879
1880 bool ldb_dn_validate(struct ldb_dn *dn);
1881
1882 char *ldb_dn_escape_value(TALLOC_CTX *mem_ctx, struct ldb_val value);
1883 const char *ldb_dn_get_casefold(struct ldb_dn *dn);
1884 char *ldb_dn_alloc_casefold(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1885
1886 int ldb_dn_compare_base(struct ldb_dn *base, struct ldb_dn *dn);
1887 int ldb_dn_compare(struct ldb_dn *edn0, struct ldb_dn *edn1);
1888
1889 bool ldb_dn_add_base(struct ldb_dn *dn, struct ldb_dn *base);
1890 bool ldb_dn_add_base_fmt(struct ldb_dn *dn, const char *base_fmt, ...) PRINTF_ATTRIBUTE(2,3);
1891 bool ldb_dn_add_child(struct ldb_dn *dn, struct ldb_dn *child);
1892 bool ldb_dn_add_child_fmt(struct ldb_dn *dn, const char *child_fmt, ...) PRINTF_ATTRIBUTE(2,3);
1893 bool ldb_dn_remove_base_components(struct ldb_dn *dn, unsigned int num);
1894 bool ldb_dn_remove_child_components(struct ldb_dn *dn, unsigned int num);
1895 bool ldb_dn_add_child_val(struct ldb_dn *dn,
1896                           const char *rdn,
1897                           struct ldb_val value);
1898
1899 struct ldb_dn *ldb_dn_copy(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1900 struct ldb_dn *ldb_dn_get_parent(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1901 char *ldb_dn_canonical_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1902 char *ldb_dn_canonical_ex_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1903 int ldb_dn_get_comp_num(struct ldb_dn *dn);
1904 int ldb_dn_get_extended_comp_num(struct ldb_dn *dn);
1905 const char *ldb_dn_get_component_name(struct ldb_dn *dn, unsigned int num);
1906 const struct ldb_val *ldb_dn_get_component_val(struct ldb_dn *dn, unsigned int num);
1907 const char *ldb_dn_get_rdn_name(struct ldb_dn *dn);
1908 const struct ldb_val *ldb_dn_get_rdn_val(struct ldb_dn *dn);
1909 int ldb_dn_set_component(struct ldb_dn *dn, int num, const char *name, const struct ldb_val val);
1910
1911 bool ldb_dn_is_valid(struct ldb_dn *dn);
1912 bool ldb_dn_is_special(struct ldb_dn *dn);
1913 bool ldb_dn_check_special(struct ldb_dn *dn, const char *check);
1914 bool ldb_dn_is_null(struct ldb_dn *dn);
1915 int ldb_dn_update_components(struct ldb_dn *dn, const struct ldb_dn *ref_dn);
1916
1917
1918 /**
1919    Compare two attributes
1920
1921    This function compares to attribute names. Note that this is a
1922    case-insensitive comparison.
1923
1924    \param a the first attribute name to compare
1925    \param b the second attribute name to compare
1926
1927    \return 0 if the attribute names are the same, or only differ in
1928    case; non-zero if there are any differences
1929
1930   attribute names are restricted by rfc2251 so using
1931   strcasecmp and toupper here is ok.
1932   return 0 for match
1933 */
1934 #define ldb_attr_cmp(a, b) strcasecmp(a, b)
1935 char *ldb_attr_casefold(TALLOC_CTX *mem_ctx, const char *s);
1936 int ldb_attr_dn(const char *attr);
1937
1938 /**
1939    Create an empty message
1940
1941    \param mem_ctx the memory context to create in. You can pass NULL
1942    to get the top level context, however the ldb context (from
1943    ldb_init()) may be a better choice
1944 */
1945 struct ldb_message *ldb_msg_new(TALLOC_CTX *mem_ctx);
1946
1947 /**
1948    Find an element within an message
1949 */
1950 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg,
1951                                                  const char *attr_name);
1952
1953 /**
1954    Compare two ldb_val values
1955
1956    \param v1 first ldb_val structure to be tested
1957    \param v2 second ldb_val structure to be tested
1958
1959    \return 1 for a match, 0 if there is any difference
1960 */
1961 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
1962
1963 /**
1964    find a value within an ldb_message_element
1965
1966    \param el the element to search
1967    \param val the value to search for
1968
1969    \note This search is case sensitive
1970 */
1971 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el,
1972                                  struct ldb_val *val);
1973
1974 /**
1975    add a new empty element to a ldb_message
1976 */
1977 int ldb_msg_add_empty(struct ldb_message *msg,
1978                 const char *attr_name,
1979                 int flags,
1980                 struct ldb_message_element **return_el);
1981
1982 /**
1983    add a element to a ldb_message
1984 */
1985 int ldb_msg_add(struct ldb_message *msg,
1986                 const struct ldb_message_element *el,
1987                 int flags);
1988 int ldb_msg_add_value(struct ldb_message *msg,
1989                 const char *attr_name,
1990                 const struct ldb_val *val,
1991                 struct ldb_message_element **return_el);
1992 int ldb_msg_add_steal_value(struct ldb_message *msg,
1993                       const char *attr_name,
1994                       struct ldb_val *val);
1995 int ldb_msg_add_steal_string(struct ldb_message *msg,
1996                              const char *attr_name, char *str);
1997 int ldb_msg_add_string(struct ldb_message *msg,
1998                        const char *attr_name, const char *str);
1999 int ldb_msg_add_linearized_dn(struct ldb_message *msg, const char *attr_name,
2000                               struct ldb_dn *dn);
2001 int ldb_msg_add_fmt(struct ldb_message *msg,
2002                     const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
2003
2004 /**
2005    compare two message elements - return 0 on match
2006 */
2007 int ldb_msg_element_compare(struct ldb_message_element *el1,
2008                             struct ldb_message_element *el2);
2009 int ldb_msg_element_compare_name(struct ldb_message_element *el1,
2010                                  struct ldb_message_element *el2);
2011
2012 /**
2013    Find elements in a message.
2014
2015    This function finds elements and converts to a specific type, with
2016    a give default value if not found. Assumes that elements are
2017    single valued.
2018 */
2019 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
2020 int ldb_msg_find_attr_as_int(const struct ldb_message *msg,
2021                              const char *attr_name,
2022                              int default_value);
2023 unsigned int ldb_msg_find_attr_as_uint(const struct ldb_message *msg,
2024                                        const char *attr_name,
2025                                        unsigned int default_value);
2026 int64_t ldb_msg_find_attr_as_int64(const struct ldb_message *msg,
2027                                    const char *attr_name,
2028                                    int64_t default_value);
2029 uint64_t ldb_msg_find_attr_as_uint64(const struct ldb_message *msg,
2030                                      const char *attr_name,
2031                                      uint64_t default_value);
2032 double ldb_msg_find_attr_as_double(const struct ldb_message *msg,
2033                                    const char *attr_name,
2034                                    double default_value);
2035 int ldb_msg_find_attr_as_bool(const struct ldb_message *msg,
2036                               const char *attr_name,
2037                               int default_value);
2038 const char *ldb_msg_find_attr_as_string(const struct ldb_message *msg,
2039                                         const char *attr_name,
2040                                         const char *default_value);
2041
2042 struct ldb_dn *ldb_msg_find_attr_as_dn(struct ldb_context *ldb,
2043                                        TALLOC_CTX *mem_ctx,
2044                                        const struct ldb_message *msg,
2045                                        const char *attr_name);
2046
2047 void ldb_msg_sort_elements(struct ldb_message *msg);
2048
2049 struct ldb_message *ldb_msg_copy_shallow(TALLOC_CTX *mem_ctx,
2050                                          const struct ldb_message *msg);
2051 struct ldb_message *ldb_msg_copy(TALLOC_CTX *mem_ctx,
2052                                  const struct ldb_message *msg);
2053
2054 /*
2055  * ldb_msg_canonicalize() is now depreciated
2056  * Please use ldb_msg_normalize() instead
2057  *
2058  * NOTE: Returned ldb_message object is allocated
2059  * into *ldb's context. Callers are recommended
2060  * to steal the returned object into a TALLOC_CTX
2061  * with short lifetime.
2062  */
2063 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb,
2064                                          const struct ldb_message *msg) _DEPRECATED_;
2065
2066 int ldb_msg_normalize(struct ldb_context *ldb,
2067                       TALLOC_CTX *mem_ctx,
2068                       const struct ldb_message *msg,
2069                       struct ldb_message **_msg_out);
2070
2071
2072 /*
2073  * ldb_msg_diff() is now depreciated
2074  * Please use ldb_msg_difference() instead
2075  *
2076  * NOTE: Returned ldb_message object is allocated
2077  * into *ldb's context. Callers are recommended
2078  * to steal the returned object into a TALLOC_CTX
2079  * with short lifetime.
2080  */
2081 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb,
2082                                  struct ldb_message *msg1,
2083                                  struct ldb_message *msg2) _DEPRECATED_;
2084
2085 /**
2086  * return a ldb_message representing the differences between msg1 and msg2.
2087  * If you then use this in a ldb_modify() call,
2088  * it can be used to save edits to a message
2089  *
2090  * Result message is constructed as follows:
2091  * - LDB_FLAG_MOD_ADD     - elements found only in msg2
2092  * - LDB_FLAG_MOD_REPLACE - elements in msg2 that have
2093  *                          different value in msg1
2094  *                          Value for msg2 element is used
2095  * - LDB_FLAG_MOD_DELETE  - elements found only in msg2
2096  *
2097  * @return LDB_SUCCESS or LDB_ERR_OPERATIONS_ERROR
2098  */
2099 int ldb_msg_difference(struct ldb_context *ldb,
2100                        TALLOC_CTX *mem_ctx,
2101                        struct ldb_message *msg1,
2102                        struct ldb_message *msg2,
2103                        struct ldb_message **_msg_out);
2104
2105 /**
2106    Tries to find a certain string attribute in a message
2107
2108    \param msg the message to check
2109    \param name attribute name
2110    \param value attribute value
2111
2112    \return 1 on match and 0 otherwise.
2113 */
2114 int ldb_msg_check_string_attribute(const struct ldb_message *msg,
2115                                    const char *name,
2116                                    const char *value);
2117
2118 /**
2119    Integrity check an ldb_message
2120
2121    This function performs basic sanity / integrity checks on an
2122    ldb_message.
2123
2124    \param ldb context in which to perform the checks
2125    \param msg the message to check
2126
2127    \return LDB_SUCCESS if the message is OK, or a non-zero error code
2128    (one of LDB_ERR_INVALID_DN_SYNTAX, LDB_ERR_ENTRY_ALREADY_EXISTS or
2129    LDB_ERR_INVALID_ATTRIBUTE_SYNTAX) if there is a problem with a
2130    message.
2131 */
2132 int ldb_msg_sanity_check(struct ldb_context *ldb,
2133                          const struct ldb_message *msg);
2134
2135 /**
2136    Duplicate an ldb_val structure
2137
2138    This function copies an ldb value structure.
2139
2140    \param mem_ctx the memory context that the duplicated value will be
2141    allocated from
2142    \param v the ldb_val to be duplicated.
2143
2144    \return the duplicated ldb_val structure.
2145 */
2146 struct ldb_val ldb_val_dup(TALLOC_CTX *mem_ctx, const struct ldb_val *v);
2147
2148 /**
2149   this allows the user to set a debug function for error reporting
2150 */
2151 int ldb_set_debug(struct ldb_context *ldb,
2152                   void (*debug)(void *context, enum ldb_debug_level level,
2153                                 const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0),
2154                   void *context);
2155
2156 /**
2157   this allows the user to set custom utf8 function for error reporting
2158 */
2159 void ldb_set_utf8_fns(struct ldb_context *ldb,
2160                       void *context,
2161                       char *(*casefold)(void *, void *, const char *, size_t n));
2162
2163 /**
2164    this sets up debug to print messages on stderr
2165 */
2166 int ldb_set_debug_stderr(struct ldb_context *ldb);
2167
2168 /* control backend specific opaque values */
2169 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
2170 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
2171
2172 const char **ldb_attr_list_copy(TALLOC_CTX *mem_ctx, const char * const *attrs);
2173 const char **ldb_attr_list_copy_add(TALLOC_CTX *mem_ctx, const char * const *attrs, const char *new_attr);
2174 int ldb_attr_in_list(const char * const *attrs, const char *attr);
2175
2176 int ldb_msg_rename_attr(struct ldb_message *msg, const char *attr, const char *replace);
2177 int ldb_msg_copy_attr(struct ldb_message *msg, const char *attr, const char *replace);
2178 void ldb_msg_remove_attr(struct ldb_message *msg, const char *attr);
2179 void ldb_msg_remove_element(struct ldb_message *msg, struct ldb_message_element *el);
2180
2181
2182 void ldb_parse_tree_attr_replace(struct ldb_parse_tree *tree,
2183                                  const char *attr,
2184                                  const char *replace);
2185
2186 /*
2187   shallow copy a tree - copying only the elements array so that the caller
2188   can safely add new elements without changing the message
2189 */
2190 struct ldb_parse_tree *ldb_parse_tree_copy_shallow(TALLOC_CTX *mem_ctx,
2191                                                    const struct ldb_parse_tree *ot);
2192
2193 /**
2194    Convert a time structure to a string
2195
2196    This function converts a time_t structure to an LDAP formatted
2197    GeneralizedTime string.
2198
2199    \param mem_ctx the memory context to allocate the return string in
2200    \param t the time structure to convert
2201
2202    \return the formatted string, or NULL if the time structure could
2203    not be converted
2204 */
2205 char *ldb_timestring(TALLOC_CTX *mem_ctx, time_t t);
2206
2207 /**
2208    Convert a string to a time structure
2209
2210    This function converts an LDAP formatted GeneralizedTime string
2211    to a time_t structure.
2212
2213    \param s the string to convert
2214
2215    \return the time structure, or 0 if the string cannot be converted
2216 */
2217 time_t ldb_string_to_time(const char *s);
2218
2219 /**
2220   convert a LDAP GeneralizedTime string in ldb_val format to a
2221   time_t.
2222 */
2223 int ldb_val_to_time(const struct ldb_val *v, time_t *t);
2224
2225 /**
2226    Convert a time structure to a string
2227
2228    This function converts a time_t structure to an LDAP formatted
2229    UTCTime string.
2230
2231    \param mem_ctx the memory context to allocate the return string in
2232    \param t the time structure to convert
2233
2234    \return the formatted string, or NULL if the time structure could
2235    not be converted
2236 */
2237 char *ldb_timestring_utc(TALLOC_CTX *mem_ctx, time_t t);
2238
2239 /**
2240    Convert a string to a time structure
2241
2242    This function converts an LDAP formatted UTCTime string
2243    to a time_t structure.
2244
2245    \param s the string to convert
2246
2247    \return the time structure, or 0 if the string cannot be converted
2248 */
2249 time_t ldb_string_utc_to_time(const char *s);
2250
2251
2252 void ldb_qsort (void *const pbase, size_t total_elems, size_t size, void *opaque, ldb_qsort_cmp_fn_t cmp);
2253
2254 #ifndef discard_const
2255 #define discard_const(ptr) ((void *)((uintptr_t)(ptr)))
2256 #endif
2257
2258 /*
2259   a wrapper around ldb_qsort() that ensures the comparison function is
2260   type safe. This will produce a compilation warning if the types
2261   don't match
2262  */
2263 #define LDB_TYPESAFE_QSORT(base, numel, opaque, comparison)     \
2264 do { \
2265         if (numel > 1) { \
2266                 ldb_qsort(base, numel, sizeof((base)[0]), discard_const(opaque), (ldb_qsort_cmp_fn_t)comparison); \
2267                 comparison(&((base)[0]), &((base)[1]), opaque);         \
2268         } \
2269 } while (0)
2270
2271 /* allow ldb to also call TYPESAFE_QSORT() */
2272 #ifndef TYPESAFE_QSORT
2273 #define TYPESAFE_QSORT(base, numel, comparison) \
2274 do { \
2275         if (numel > 1) { \
2276                 qsort(base, numel, sizeof((base)[0]), (int (*)(const void *, const void *))comparison); \
2277                 comparison(&((base)[0]), &((base)[1])); \
2278         } \
2279 } while (0)
2280 #endif
2281
2282
2283
2284 /**
2285    Convert a control into its string representation.
2286
2287    \param mem_ctx TALLOC context to return result on, and to allocate error_string on
2288    \param control A struct ldb_control to convert
2289
2290    \return string representation of the control
2291 */
2292 char* ldb_control_to_string(TALLOC_CTX *mem_ctx, const struct ldb_control *control);
2293 /**
2294    Convert a string representing a control into a ldb_control structure
2295
2296    \param ldb LDB context
2297    \param mem_ctx TALLOC context to return result on, and to allocate error_string on
2298    \param control_strings A string-formatted control
2299
2300    \return a ldb_control element
2301 */
2302 struct ldb_control *ldb_parse_control_from_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *control_strings);
2303 /**
2304    Convert an array of string represention of a control into an array of ldb_control structures
2305
2306    \param ldb LDB context
2307    \param mem_ctx TALLOC context to return result on, and to allocate error_string on
2308    \param control_strings Array of string-formatted controls
2309
2310    \return array of ldb_control elements
2311 */
2312 struct ldb_control **ldb_parse_control_strings(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char **control_strings);
2313
2314 /**
2315    return the ldb flags
2316 */
2317 unsigned int ldb_get_flags(struct ldb_context *ldb);
2318
2319 /* set the ldb flags */
2320 void ldb_set_flags(struct ldb_context *ldb, unsigned flags);
2321
2322
2323 struct ldb_dn *ldb_dn_binary_from_ldb_val(TALLOC_CTX *mem_ctx,
2324                                           struct ldb_context *ldb,
2325                                           const struct ldb_val *strdn);
2326
2327 int ldb_dn_get_binary(struct ldb_dn *dn, struct ldb_val *val);
2328 int ldb_dn_set_binary(struct ldb_dn *dn, struct ldb_val *val);
2329
2330 /* debugging functions for ldb requests */
2331 void ldb_req_set_location(struct ldb_request *req, const char *location);
2332 const char *ldb_req_location(struct ldb_request *req);
2333
2334 /* set the location marker on a request handle - used for debugging */
2335 #define LDB_REQ_SET_LOCATION(req) ldb_req_set_location(req, __location__)
2336
2337 /*
2338   minimise a DN. The caller must pass in a validated DN.
2339
2340   If the DN has an extended component then only the first extended
2341   component is kept, the DN string is stripped.
2342
2343   The existing dn is modified
2344  */
2345 bool ldb_dn_minimise(struct ldb_dn *dn);
2346
2347 /*
2348   compare a ldb_val to a string
2349 */
2350 int ldb_val_string_cmp(const struct ldb_val *v, const char *str);
2351
2352 #endif