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