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