source4/lib/ldb/include/ldb.h

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