source4/lib/ldb/include/ldb.h

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