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 /**
 460    OID for the paged results control. This control is included in the
 461    searchRequest and searchResultDone messages as part of the controls
 462    field of the LDAPMessage, as defined in Section 4.1.12 of
 463    LDAP v3.
 464
 465    \sa <a href="http://www.ietf.org/rfc/rfc2696.txt">RFC 2696</a>.
 466 */
 467 #define LDB_CONTROL_PAGED_RESULTS_OID   "1.2.840.113556.1.4.319"
 468
 469 /**
 470    OID for specifying the returned elements of the ntSecurityDescriptor
 471
 472    \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>
 473 */
 474 #define LDB_CONTROL_SD_FLAGS_OID        "1.2.840.113556.1.4.801"
 475
 476 /**
 477    OID for specifying an advanced scope for the search (one partition)
 478
 479    \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>
 480 */
 481 #define LDB_CONTROL_DOMAIN_SCOPE_OID    "1.2.840.113556.1.4.1339"
 482
 483 /**
 484    OID for specifying an advanced scope for a search
 485
 486    \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>
 487 */
 488 #define LDB_CONTROL_SEARCH_OPTIONS_OID  "1.2.840.113556.1.4.1340"
 489
 490 /**
 491    OID for notification
 492
 493    \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>
 494 */
 495 #define LDB_CONTROL_NOTIFICATION_OID    "1.2.840.113556.1.4.528"
 496
 497 /**
 498    OID for getting deleted objects
 499
 500    \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>
 501 */
 502 #define LDB_CONTROL_SHOW_DELETED_OID    "1.2.840.113556.1.4.417"
 503
 504 /**
 505    OID for getting recycled objects
 506
 507    \sa <a href="http://msdn.microsoft.com/en-us/library/dd304621(PROT.13).aspx">Microsoft documentation of this OID</a>
 508 */
 509 #define LDB_CONTROL_SHOW_RECYCLED_OID         "1.2.840.113556.1.4.2064"
 510
 511 /**
 512    OID for getting deactivated linked attributes
 513
 514    \sa <a href="http://msdn.microsoft.com/en-us/library/dd302781(PROT.13).aspx">Microsoft documentation of this OID</a>
 515 */
 516 #define LDB_CONTROL_SHOW_DEACTIVATED_LINK_OID "1.2.840.113556.1.4.2065"
 517
 518 /**
 519    OID for extended DN
 520
 521    \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>
 522 */
 523 #define LDB_CONTROL_EXTENDED_DN_OID     "1.2.840.113556.1.4.529"
 524
 525 /**
 526    OID for LDAP server sort result extension.
 527
 528    This control is included in the searchRequest message as part of
 529    the controls field of the LDAPMessage, as defined in Section 4.1.12
 530    of LDAP v3. The controlType is set to
 531    "1.2.840.113556.1.4.473". The criticality MAY be either TRUE or
 532    FALSE (where absent is also equivalent to FALSE) at the client's
 533    option.
 534
 535    \sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
 536 */
 537 #define LDB_CONTROL_SERVER_SORT_OID     "1.2.840.113556.1.4.473"
 538
 539 /**
 540    OID for LDAP server sort result response extension.
 541
 542    This control is included in the searchResultDone message as part of
 543    the controls field of the LDAPMessage, as defined in Section 4.1.12 of
 544    LDAP v3.
 545
 546    \sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
 547 */
 548 #define LDB_CONTROL_SORT_RESP_OID       "1.2.840.113556.1.4.474"
 549
 550 /**
 551    OID for LDAP Attribute Scoped Query extension.
 552
 553    This control is included in SearchRequest or SearchResponse
 554    messages as part of the controls field of the LDAPMessage.
 555 */
 556 #define LDB_CONTROL_ASQ_OID             "1.2.840.113556.1.4.1504"
 557
 558 /**
 559    OID for LDAP Directory Sync extension.
 560
 561    This control is included in SearchRequest or SearchResponse
 562    messages as part of the controls field of the LDAPMessage.
 563 */
 564 #define LDB_CONTROL_DIRSYNC_OID         "1.2.840.113556.1.4.841"
 565
 566
 567 /**
 568    OID for LDAP Virtual List View Request extension.
 569
 570    This control is included in SearchRequest messages
 571    as part of the controls field of the LDAPMessage.
 572 */
 573 #define LDB_CONTROL_VLV_REQ_OID         "2.16.840.1.113730.3.4.9"
 574
 575 /**
 576    OID for LDAP Virtual List View Response extension.
 577
 578    This control is included in SearchResponse messages
 579    as part of the controls field of the LDAPMessage.
 580 */
 581 #define LDB_CONTROL_VLV_RESP_OID        "2.16.840.1.113730.3.4.10"
 582
 583 /**
 584    OID to let modifies don't give an error when adding an existing
 585    attribute with the same value or deleting an nonexisting one attribute
 586
 587    \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>
 588 */
 589 #define LDB_CONTROL_PERMISSIVE_MODIFY_OID       "1.2.840.113556.1.4.1413"
 590
 591 /**
 592    OID for LDAP Extended Operation START_TLS.
 593
 594    This Extended operation is used to start a new TLS
 595    channel on top of a clear text channel.
 596 */
 597 #define LDB_EXTENDED_START_TLS_OID      "1.3.6.1.4.1.1466.20037"
 598
 599 /**
 600 */
 601 #define LDB_EXTENDED_DYNAMIC_OID        "1.3.6.1.4.1.1466.101.119.1"
 602
 603 /**
 604 */
 605 #define LDB_EXTENDED_FAST_BIND_OID      "1.2.840.113556.1.4.1781"
 606
 607 struct ldb_sd_flags_control {
 608         /*
 609          * request the owner    0x00000001
 610          * request the group    0x00000002
 611          * request the DACL     0x00000004
 612          * request the SACL     0x00000008
 613          */
 614         unsigned secinfo_flags;
 615 };
 616
 617 /*
 618  * DOMAIN_SCOPE         0x00000001
 619  * this limits the search to one partition,
 620  * and no referrals will be returned.
 621  * (Note this doesn't limit the entries by there
 622  *  objectSid belonging to a domain! Builtin and Foreign Sids
 623  *  are still returned)
 624  *
 625  * PHANTOM_ROOT         0x00000002
 626  * this search on the whole tree on a domain controller
 627  * over multiple partitions without referrals.
 628  * (This is the default behavior on the Global Catalog Port)
 629  */
 630
 631 #define LDB_SEARCH_OPTION_DOMAIN_SCOPE 0x00000001
 632 #define LDB_SEARCH_OPTION_PHANTOM_ROOT 0x00000002
 633
 634 struct ldb_search_options_control {
 635         unsigned search_options;
 636 };
 637
 638 struct ldb_paged_control {
 639         int size;
 640         int cookie_len;
 641         char *cookie;
 642 };
 643
 644 struct ldb_extended_dn_control {
 645         int type;
 646 };
 647
 648 struct ldb_server_sort_control {
 649         const char *attributeName;
 650         const char *orderingRule;
 651         int reverse;
 652 };
 653
 654 struct ldb_sort_resp_control {
 655         int result;
 656         char *attr_desc;
 657 };
 658
 659 struct ldb_asq_control {
 660         int request;
 661         char *source_attribute;
 662         int src_attr_len;
 663         int result;
 664 };
 665
 666 struct ldb_dirsync_control {
 667         int flags;
 668         int max_attributes;
 669         int cookie_len;
 670         char *cookie;
 671 };
 672
 673 struct ldb_vlv_req_control {
 674         int beforeCount;
 675         int afterCount;
 676         int type;
 677         union {
 678                 struct {
 679                         int offset;
 680                         int contentCount;
 681                 } byOffset;
 682                 struct {
 683                         int value_len;
 684                         char *value;
 685                 } gtOrEq;
 686         } match;
 687         int ctxid_len;
 688         char *contextId;
 689 };
 690
 691 struct ldb_vlv_resp_control {
 692         int targetPosition;
 693         int contentCount;
 694         int vlv_result;
 695         int ctxid_len;
 696         char *contextId;
 697 };
 698
 699 struct ldb_control {
 700         const char *oid;
 701         int critical;
 702         void *data;
 703 };
 704
 705 enum ldb_request_type {
 706         LDB_SEARCH,
 707         LDB_ADD,
 708         LDB_MODIFY,
 709         LDB_DELETE,
 710         LDB_RENAME,
 711         LDB_EXTENDED,
 712         LDB_REQ_REGISTER_CONTROL,
 713         LDB_REQ_REGISTER_PARTITION
 714 };
 715
 716 enum ldb_reply_type {
 717         LDB_REPLY_ENTRY,
 718         LDB_REPLY_REFERRAL,
 719         LDB_REPLY_DONE
 720 };
 721
 722 enum ldb_wait_type {
 723         LDB_WAIT_ALL,
 724         LDB_WAIT_NONE
 725 };
 726
 727 enum ldb_state {
 728         LDB_ASYNC_INIT,
 729         LDB_ASYNC_PENDING,
 730         LDB_ASYNC_DONE
 731 };
 732
 733 struct ldb_extended {
 734         const char *oid;
 735         void *data; /* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
 736 };
 737
 738 #define LDB_EXTENDED_SEQUENCE_NUMBER    "1.3.6.1.4.1.7165.4.4.3"
 739
 740 enum ldb_sequence_type {
 741         LDB_SEQ_HIGHEST_SEQ,
 742         LDB_SEQ_HIGHEST_TIMESTAMP,
 743         LDB_SEQ_NEXT
 744 };
 745
 746 #define LDB_SEQ_GLOBAL_SEQUENCE    0x01
 747 #define LDB_SEQ_TIMESTAMP_SEQUENCE 0x02
 748
 749 struct ldb_seqnum_request {
 750         enum ldb_sequence_type type;
 751 };
 752
 753 struct ldb_seqnum_result {
 754         uint64_t seq_num;
 755         uint32_t flags;
 756 };
 757
 758 struct ldb_result {
 759         unsigned int count;
 760         struct ldb_message **msgs;
 761         struct ldb_extended *extended;
 762         struct ldb_control **controls;
 763         char **refs;
 764 };
 765
 766 struct ldb_reply {
 767         int error;
 768         enum ldb_reply_type type;
 769         struct ldb_message *message;
 770         struct ldb_extended *response;
 771         struct ldb_control **controls;
 772         char *referral;
 773 };
 774
 775 struct ldb_request;
 776 struct ldb_handle;
 777
 778 struct ldb_search {
 779         struct ldb_dn *base;
 780         enum ldb_scope scope;
 781         struct ldb_parse_tree *tree;
 782         const char * const *attrs;
 783         struct ldb_result *res;
 784 };
 785
 786 struct ldb_add {
 787         const struct ldb_message *message;
 788 };
 789
 790 struct ldb_modify {
 791         const struct ldb_message *message;
 792 };
 793
 794 struct ldb_delete {
 795         struct ldb_dn *dn;
 796 };
 797
 798 struct ldb_rename {
 799         struct ldb_dn *olddn;
 800         struct ldb_dn *newdn;
 801 };
 802
 803 struct ldb_register_control {
 804         const char *oid;
 805 };
 806
 807 struct ldb_register_partition {
 808         struct ldb_dn *dn;
 809 };
 810
 811 typedef int (*ldb_request_callback_t)(struct ldb_request *, struct ldb_reply *);
 812
 813 struct ldb_request {
 814
 815         enum ldb_request_type operation;
 816
 817         union {
 818                 struct ldb_search search;
 819                 struct ldb_add    add;
 820                 struct ldb_modify mod;
 821                 struct ldb_delete del;
 822                 struct ldb_rename rename;
 823                 struct ldb_extended extended;
 824                 struct ldb_register_control reg_control;
 825                 struct ldb_register_partition reg_partition;
 826         } op;
 827
 828         struct ldb_control **controls;
 829
 830         void *context;
 831         ldb_request_callback_t callback;
 832
 833         int timeout;
 834         time_t starttime;
 835         struct ldb_handle *handle;
 836 };
 837
 838 int ldb_request(struct ldb_context *ldb, struct ldb_request *request);
 839 int ldb_request_done(struct ldb_request *req, int status);
 840 bool ldb_request_is_done(struct ldb_request *req);
 841
 842 int ldb_modules_wait(struct ldb_handle *handle);
 843 int ldb_wait(struct ldb_handle *handle, enum ldb_wait_type type);
 844
 845 int ldb_set_timeout(struct ldb_context *ldb, struct ldb_request *req, int timeout);
 846 int ldb_set_timeout_from_prev_req(struct ldb_context *ldb, struct ldb_request *oldreq, struct ldb_request *newreq);
 847 void ldb_set_create_perms(struct ldb_context *ldb, unsigned int perms);
 848 void ldb_set_modules_dir(struct ldb_context *ldb, const char *path);
 849 struct tevent_context;
 850 void ldb_set_event_context(struct ldb_context *ldb, struct tevent_context *ev);
 851 struct tevent_context * ldb_get_event_context(struct ldb_context *ldb);
 852
 853 /**
 854   Initialise ldbs' global information
 855
 856   This is required before any other LDB call
 857
 858   \return 0 if initialisation succeeded, -1 otherwise
 859 */
 860 int ldb_global_init(void);
 861
 862 /**
 863   Initialise an ldb context
 864
 865   This is required before any other LDB call.
 866
 867   \param mem_ctx pointer to a talloc memory context. Pass NULL if there is
 868   no suitable context available.
 869
 870   \return pointer to ldb_context that should be free'd (using talloc_free())
 871   at the end of the program.
 872 */
 873 struct ldb_context *ldb_init(TALLOC_CTX *mem_ctx, struct tevent_context *ev_ctx);
 874
 875 /**
 876    Connect to a database.
 877
 878    This is typically called soon after ldb_init(), and is required prior to
 879    any search or database modification operations.
 880
 881    The URL can be one of the following forms:
 882     - tdb://path
 883     - ldapi://path
 884     - ldap://host
 885     - sqlite://path
 886
 887    \param ldb the context associated with the database (from ldb_init())
 888    \param url the URL of the database to connect to, as noted above
 889    \param flags a combination of LDB_FLG_* to modify the connection behaviour
 890    \param options backend specific options - passed uninterpreted to the backend
 891
 892    \return result code (LDB_SUCCESS on success, or a failure code)
 893
 894    \note It is an error to connect to a database that does not exist in readonly mode
 895    (that is, with LDB_FLG_RDONLY). However in read-write mode, the database will be
 896    created if it does not exist.
 897 */
 898
 899 typedef void (*ldb_async_timeout_fn) (void *);
 900 typedef bool (*ldb_async_callback_fn) (void *);
 901 typedef int (*ldb_async_ctx_add_op_fn)(void *, time_t, void *, ldb_async_timeout_fn, ldb_async_callback_fn);
 902 typedef int (*ldb_async_ctx_wait_op_fn)(void *);
 903
 904 void ldb_async_ctx_set_private_data(struct ldb_context *ldb,
 905                                         void *private_data);
 906 void ldb_async_ctx_set_add_op(struct ldb_context *ldb,
 907                                 ldb_async_ctx_add_op_fn add_op);
 908 void ldb_async_ctx_set_wait_op(struct ldb_context *ldb,
 909                                 ldb_async_ctx_wait_op_fn wait_op);
 910
 911 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
 912
 913 /*
 914   return an automatic basedn from the rootDomainNamingContext of the rootDSE
 915   This value have been set in an opaque pointer at connection time
 916 */
 917 struct ldb_dn *ldb_get_root_basedn(struct ldb_context *ldb);
 918
 919 /*
 920   return an automatic basedn from the configurationNamingContext of the rootDSE
 921   This value have been set in an opaque pointer at connection time
 922 */
 923 struct ldb_dn *ldb_get_config_basedn(struct ldb_context *ldb);
 924
 925 /*
 926   return an automatic basedn from the schemaNamingContext of the rootDSE
 927   This value have been set in an opaque pointer at connection time
 928 */
 929 struct ldb_dn *ldb_get_schema_basedn(struct ldb_context *ldb);
 930
 931 /*
 932   return an automatic baseDN from the defaultNamingContext of the rootDSE
 933   This value have been set in an opaque pointer at connection time
 934 */
 935 struct ldb_dn *ldb_get_default_basedn(struct ldb_context *ldb);
 936
 937 /**
 938   The default async search callback function
 939
 940   \param req the request we are callback of
 941   \param ares a single reply from the async core
 942
 943   \return result code (LDB_SUCCESS on success, or a failure code)
 944
 945   \note this function expects req->context to always be an struct ldb_result pointer
 946   AND a talloc context, this function will steal on the context each message
 947   from the ares reply passed on by the async core so that in the end all the
 948   messages will be in the context (ldb_result)  memory tree.
 949   Freeing the passed context (ldb_result tree) will free all the resources
 950   (the request need to be freed separately and the result doe not depend on the
 951   request that can be freed as sson as the search request is finished)
 952 */
 953
 954 int ldb_search_default_callback(struct ldb_request *req, struct ldb_reply *ares);
 955
 956 /**
 957   The default async extended operation callback function
 958
 959   \param req the request we are callback of
 960   \param ares a single reply from the async core
 961
 962   \return result code (LDB_SUCCESS on success, or a failure code)
 963 */
 964 int ldb_op_default_callback(struct ldb_request *req, struct ldb_reply *ares);
 965
 966
 967 /**
 968   Helper function to build a search request
 969
 970   \param ret_req the request structure is returned here (talloced on mem_ctx)
 971   \param ldb the context associated with the database (from ldb_init())
 972   \param mem_ctx a talloc memory context (used as parent of ret_req)
 973   \param base the Base Distinguished Name for the query (use ldb_dn_new() for an empty one)
 974   \param scope the search scope for the query
 975   \param expression the search expression to use for this query
 976   \param attrs the search attributes for the query (pass NULL if none required)
 977   \param controls an array of controls
 978   \param context the callback function context
 979   \param the callback function to handle the async replies
 980   \param the parent request if any
 981
 982   \return result code (LDB_SUCCESS on success, or a failure code)
 983 */
 984
 985 int ldb_build_search_req(struct ldb_request **ret_req,
 986                         struct ldb_context *ldb,
 987                         TALLOC_CTX *mem_ctx,
 988                         struct ldb_dn *base,
 989                         enum ldb_scope scope,
 990                         const char *expression,
 991                         const char * const *attrs,
 992                         struct ldb_control **controls,
 993                         void *context,
 994                         ldb_request_callback_t callback,
 995                         struct ldb_request *parent);
 996
 997 int ldb_build_search_req_ex(struct ldb_request **ret_req,
 998                         struct ldb_context *ldb,
 999                         TALLOC_CTX *mem_ctx,
1000                         struct ldb_dn *base,
1001                         enum ldb_scope scope,
1002                         struct ldb_parse_tree *tree,
1003                         const char * const *attrs,
1004                         struct ldb_control **controls,
1005                         void *context,
1006                         ldb_request_callback_t callback,
1007                         struct ldb_request *parent);
1008
1009 /**
1010   Helper function to build an add request
1011
1012   \param ret_req the request structure is returned here (talloced on mem_ctx)
1013   \param ldb the context associated with the database (from ldb_init())
1014   \param mem_ctx a talloc memory context (used as parent of ret_req)
1015   \param message contains the entry to be added
1016   \param controls an array of controls
1017   \param context the callback function context
1018   \param the callback function to handle the async replies
1019   \param the parent request if any
1020
1021   \return result code (LDB_SUCCESS on success, or a failure code)
1022 */
1023
1024 int ldb_build_add_req(struct ldb_request **ret_req,
1025                         struct ldb_context *ldb,
1026                         TALLOC_CTX *mem_ctx,
1027                         const struct ldb_message *message,
1028                         struct ldb_control **controls,
1029                         void *context,
1030                         ldb_request_callback_t callback,
1031                         struct ldb_request *parent);
1032
1033 /**
1034   Helper function to build a modify request
1035
1036   \param ret_req the request structure is returned here (talloced on mem_ctx)
1037   \param ldb the context associated with the database (from ldb_init())
1038   \param mem_ctx a talloc memory context (used as parent of ret_req)
1039   \param message contains the entry to be modified
1040   \param controls an array of controls
1041   \param context the callback function context
1042   \param the callback function to handle the async replies
1043   \param the parent request if any
1044
1045   \return result code (LDB_SUCCESS on success, or a failure code)
1046 */
1047
1048 int ldb_build_mod_req(struct ldb_request **ret_req,
1049                         struct ldb_context *ldb,
1050                         TALLOC_CTX *mem_ctx,
1051                         const struct ldb_message *message,
1052                         struct ldb_control **controls,
1053                         void *context,
1054                         ldb_request_callback_t callback,
1055                         struct ldb_request *parent);
1056
1057 /**
1058   Helper function to build a delete request
1059
1060   \param ret_req the request structure is returned here (talloced on mem_ctx)
1061   \param ldb the context associated with the database (from ldb_init())
1062   \param mem_ctx a talloc memory context (used as parent of ret_req)
1063   \param dn the DN to be deleted
1064   \param controls an array of controls
1065   \param context the callback function context
1066   \param the callback function to handle the async replies
1067   \param the parent request if any
1068
1069   \return result code (LDB_SUCCESS on success, or a failure code)
1070 */
1071
1072 int ldb_build_del_req(struct ldb_request **ret_req,
1073                         struct ldb_context *ldb,
1074                         TALLOC_CTX *mem_ctx,
1075                         struct ldb_dn *dn,
1076                         struct ldb_control **controls,
1077                         void *context,
1078                         ldb_request_callback_t callback,
1079                         struct ldb_request *parent);
1080
1081 /**
1082   Helper function to build a rename request
1083
1084   \param ret_req the request structure is returned here (talloced on mem_ctx)
1085   \param ldb the context associated with the database (from ldb_init())
1086   \param mem_ctx a talloc memory context (used as parent of ret_req)
1087   \param olddn the old DN
1088   \param newdn the new DN
1089   \param controls an array of controls
1090   \param context the callback function context
1091   \param the callback function to handle the async replies
1092   \param the parent request if any
1093
1094   \return result code (LDB_SUCCESS on success, or a failure code)
1095 */
1096
1097 int ldb_build_rename_req(struct ldb_request **ret_req,
1098                         struct ldb_context *ldb,
1099                         TALLOC_CTX *mem_ctx,
1100                         struct ldb_dn *olddn,
1101                         struct ldb_dn *newdn,
1102                         struct ldb_control **controls,
1103                         void *context,
1104                         ldb_request_callback_t callback,
1105                         struct ldb_request *parent);
1106
1107 /**
1108   Add a ldb_control to a ldb_request
1109
1110   \param req the request struct where to add the control
1111   \param oid the object identifier of the control as string
1112   \param critical whether the control should be critical or not
1113   \param data a talloc pointer to the control specific data
1114
1115   \return result code (LDB_SUCCESS on success, or a failure code)
1116 */
1117 int ldb_request_add_control(struct ldb_request *req, const char *oid, bool critical, void *data);
1118
1119 /**
1120    check if a control with the specified "oid" exist and return it
1121   \param req the request struct where to add the control
1122   \param oid the object identifier of the control as string
1123
1124   \return the control, NULL if not found
1125 */
1126 struct ldb_control *ldb_request_get_control(struct ldb_request *req, const char *oid);
1127
1128 /**
1129    check if a control with the specified "oid" exist and return it
1130   \param rep the reply struct where to add the control
1131   \param oid the object identifier of the control as string
1132
1133   \return the control, NULL if not found
1134 */
1135 struct ldb_control *ldb_reply_get_control(struct ldb_reply *rep, const char *oid);
1136
1137 /**
1138   Search the database
1139
1140   This function searches the database, and returns
1141   records that match an LDAP-like search expression
1142
1143   \param ldb the context associated with the database (from ldb_init())
1144   \param mem_ctx the memory context to use for the request and the results
1145   \param result the return result
1146   \param base the Base Distinguished Name for the query (use ldb_dn_new() for an empty one)
1147   \param scope the search scope for the query
1148   \param attrs the search attributes for the query (pass NULL if none required)
1149   \param exp_fmt the search expression to use for this query (printf like)
1150
1151   \return result code (LDB_SUCCESS on success, or a failure code)
1152
1153   \note use talloc_free() to free the ldb_result returned
1154 */
1155 int ldb_search(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
1156                struct ldb_result **result, struct ldb_dn *base,
1157                enum ldb_scope scope, const char * const *attrs,
1158                const char *exp_fmt, ...) PRINTF_ATTRIBUTE(7,8);
1159
1160 /**
1161   Add a record to the database.
1162
1163   This function adds a record to the database. This function will fail
1164   if a record with the specified class and key already exists in the
1165   database.
1166
1167   \param ldb the context associated with the database (from
1168   ldb_init())
1169   \param message the message containing the record to add.
1170
1171   \return result code (LDB_SUCCESS if the record was added, otherwise
1172   a failure code)
1173 */
1174 int ldb_add(struct ldb_context *ldb,
1175             const struct ldb_message *message);
1176
1177 /**
1178   Modify the specified attributes of a record
1179
1180   This function modifies a record that is in the database.
1181
1182   \param ldb the context associated with the database (from
1183   ldb_init())
1184   \param message the message containing the changes required.
1185
1186   \return result code (LDB_SUCCESS if the record was modified as
1187   requested, otherwise a failure code)
1188 */
1189 int ldb_modify(struct ldb_context *ldb,
1190                const struct ldb_message *message);
1191
1192 /**
1193   Rename a record in the database
1194
1195   This function renames a record in the database.
1196
1197   \param ldb the context associated with the database (from
1198   ldb_init())
1199   \param olddn the DN for the record to be renamed.
1200   \param newdn the new DN
1201
1202   \return result code (LDB_SUCCESS if the record was renamed as
1203   requested, otherwise a failure code)
1204 */
1205 int ldb_rename(struct ldb_context *ldb, struct ldb_dn *olddn, struct ldb_dn *newdn);
1206
1207 /**
1208   Delete a record from the database
1209
1210   This function deletes a record from the database.
1211
1212   \param ldb the context associated with the database (from
1213   ldb_init())
1214   \param dn the DN for the record to be deleted.
1215
1216   \return result code (LDB_SUCCESS if the record was deleted,
1217   otherwise a failure code)
1218 */
1219 int ldb_delete(struct ldb_context *ldb, struct ldb_dn *dn);
1220
1221 /**
1222   The default async extended operation callback function
1223
1224   \param req the request we are callback of
1225   \param ares a single reply from the async core
1226
1227   \return result code (LDB_SUCCESS on success, or a failure code)
1228
1229   \note this function expects req->context to always be an struct ldb_result pointer
1230   AND a talloc context, this function will steal on the context each message
1231   from the ares reply passed on by the async core so that in the end all the
1232   messages will be in the context (ldb_result)  memory tree.
1233   Freeing the passed context (ldb_result tree) will free all the resources
1234   (the request need to be freed separately and the result doe not depend on the
1235   request that can be freed as sson as the search request is finished)
1236 */
1237
1238 int ldb_extended_default_callback(struct ldb_request *req, struct ldb_reply *ares);
1239
1240
1241 /**
1242   Helper function to build a extended request
1243
1244   \param ret_req the request structure is returned here (talloced on mem_ctx)
1245   \param ldb the context associated with the database (from ldb_init())
1246   \param mem_ctx a talloc memory context (used as parent of ret_req)
1247   \param oid the OID of the extended operation.
1248   \param data a void pointer a the extended operation specific parameters,
1249   it needs to be NULL or a valid talloc pointer! talloc_get_type() will be used on it
1250   \param controls an array of controls
1251   \param context the callback function context
1252   \param the callback function to handle the async replies
1253   \param the parent request if any
1254
1255   \return result code (LDB_SUCCESS on success, or a failure code)
1256 */
1257 int ldb_build_extended_req(struct ldb_request **ret_req,
1258                            struct ldb_context *ldb,
1259                            TALLOC_CTX *mem_ctx,
1260                            const char *oid,
1261                            void *data,/* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
1262                            struct ldb_control **controls,
1263                            void *context,
1264                            ldb_request_callback_t callback,
1265                            struct ldb_request *parent);
1266
1267 /**
1268   call an extended operation
1269
1270   This function deletes a record from the database.
1271
1272   \param ldb the context associated with the database (from ldb_init())
1273   \param oid the OID of the extended operation.
1274   \param data a void pointer a the extended operation specific parameters,
1275   it needs to be NULL or a valid talloc pointer! talloc_get_type() will be used on it
1276   \param res the result of the extended operation
1277
1278   \return result code (LDB_SUCCESS if the extended operation returned fine,
1279   otherwise a failure code)
1280 */
1281 int ldb_extended(struct ldb_context *ldb,
1282                  const char *oid,
1283                  void *data,/* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
1284                  struct ldb_result **res);
1285
1286 /**
1287   Obtain current/next database sequence number
1288 */
1289 int ldb_sequence_number(struct ldb_context *ldb, enum ldb_sequence_type type, uint64_t *seq_num);
1290
1291 /**
1292   start a transaction
1293 */
1294 int ldb_transaction_start(struct ldb_context *ldb);
1295
1296 /**
1297    first phase of two phase commit
1298  */
1299 int ldb_transaction_prepare_commit(struct ldb_context *ldb);
1300
1301 /**
1302   commit a transaction
1303 */
1304 int ldb_transaction_commit(struct ldb_context *ldb);
1305
1306 /**
1307   cancel a transaction
1308 */
1309 int ldb_transaction_cancel(struct ldb_context *ldb);
1310
1311
1312 /**
1313   return extended error information from the last call
1314 */
1315 const char *ldb_errstring(struct ldb_context *ldb);
1316
1317 /**
1318   return a string explaining what a ldb error constant meancs
1319 */
1320 const char *ldb_strerror(int ldb_err);
1321
1322 /**
1323   setup the default utf8 functions
1324   FIXME: these functions do not yet handle utf8
1325 */
1326 void ldb_set_utf8_default(struct ldb_context *ldb);
1327
1328 /**
1329    Casefold a string
1330
1331    \param ldb the ldb context
1332    \param mem_ctx the memory context to allocate the result string
1333    memory from.
1334    \param s the string that is to be folded
1335    \return a copy of the string, converted to upper case
1336
1337    \note The default function is not yet UTF8 aware. Provide your own
1338          set of functions through ldb_set_utf8_fns()
1339 */
1340 char *ldb_casefold(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *s, size_t n);
1341
1342 /**
1343    Check the attribute name is valid according to rfc2251
1344    \param s the string to check
1345
1346    \return 1 if the name is ok
1347 */
1348 int ldb_valid_attr_name(const char *s);
1349
1350 /*
1351   ldif manipulation functions
1352 */
1353
1354 /**
1355    Write an LDIF message
1356
1357    This function writes an LDIF message using a caller supplied  write
1358    function.
1359
1360    \param ldb the ldb context (from ldb_init())
1361    \param fprintf_fn a function pointer for the write function. This must take
1362    a private data pointer, followed by a format string, and then a variable argument
1363    list.
1364    \param private_data pointer that will be provided back to the write
1365    function. This is useful for maintaining state or context.
1366    \param ldif the message to write out
1367
1368    \return the total number of bytes written, or an error code as returned
1369    from the write function.
1370
1371    \sa ldb_ldif_write_file for a more convenient way to write to a
1372    file stream.
1373
1374    \sa ldb_ldif_read for the reader equivalent to this function.
1375 */
1376 int ldb_ldif_write(struct ldb_context *ldb,
1377                    int (*fprintf_fn)(void *, const char *, ...) PRINTF_ATTRIBUTE(2,3),
1378                    void *private_data,
1379                    const struct ldb_ldif *ldif);
1380
1381 /**
1382    Clean up an LDIF message
1383
1384    This function cleans up a LDIF message read using ldb_ldif_read()
1385    or related functions (such as ldb_ldif_read_string() and
1386    ldb_ldif_read_file().
1387
1388    \param ldb the ldb context (from ldb_init())
1389    \param msg the message to clean up and free
1390
1391 */
1392 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *msg);
1393
1394 /**
1395    Read an LDIF message
1396
1397    This function creates an LDIF message using a caller supplied read
1398    function.
1399
1400    \param ldb the ldb context (from ldb_init())
1401    \param fgetc_fn a function pointer for the read function. This must
1402    take a private data pointer, and must return a pointer to an
1403    integer corresponding to the next byte read (or EOF if there is no
1404    more data to be read).
1405    \param private_data pointer that will be provided back to the read
1406    function. This is udeful for maintaining state or context.
1407
1408    \return the LDIF message that has been read in
1409
1410    \note You must free the LDIF message when no longer required, using
1411    ldb_ldif_read_free().
1412
1413    \sa ldb_ldif_read_file for a more convenient way to read from a
1414    file stream.
1415
1416    \sa ldb_ldif_read_string for a more convenient way to read from a
1417    string (char array).
1418
1419    \sa ldb_ldif_write for the writer equivalent to this function.
1420 */
1421 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
1422                                int (*fgetc_fn)(void *), void *private_data);
1423
1424 /**
1425    Read an LDIF message from a file
1426
1427    This function reads the next LDIF message from the contents of a
1428    file stream. If you want to get all of the LDIF messages, you will
1429    need to repeatedly call this function, until it returns NULL.
1430
1431    \param ldb the ldb context (from ldb_init())
1432    \param f the file stream to read from (typically from fdopen())
1433
1434    \sa ldb_ldif_read_string for an equivalent function that will read
1435    from a string (char array).
1436
1437    \sa ldb_ldif_write_file for the writer equivalent to this function.
1438
1439 */
1440 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
1441
1442 /**
1443    Read an LDIF message from a string
1444
1445    This function reads the next LDIF message from the contents of a char
1446    array. If you want to get all of the LDIF messages, you will need
1447    to repeatedly call this function, until it returns NULL.
1448
1449    \param ldb the ldb context (from ldb_init())
1450    \param s pointer to the char array to read from
1451
1452    \sa ldb_ldif_read_file for an equivalent function that will read
1453    from a file stream.
1454
1455    \sa ldb_ldif_write for a more general (arbitrary read function)
1456    version of this function.
1457 */
1458 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
1459
1460 /**
1461    Write an LDIF message to a file
1462
1463    \param ldb the ldb context (from ldb_init())
1464    \param f the file stream to write to (typically from fdopen())
1465    \param msg the message to write out
1466
1467    \return the total number of bytes written, or a negative error code
1468
1469    \sa ldb_ldif_read_file for the reader equivalent to this function.
1470 */
1471 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
1472
1473 /**
1474    Write an LDIF message to a string
1475
1476    \param ldb the ldb context (from ldb_init())
1477    \param mem_ctx the talloc context on which to attach the string)
1478    \param msg the message to write out
1479
1480    \return the string containing the LDIF, or NULL on error
1481
1482    \sa ldb_ldif_read_string for the reader equivalent to this function.
1483 */
1484 char * ldb_ldif_write_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
1485                           const struct ldb_ldif *msg);
1486
1487
1488 /*
1489    Produce a string form of an ldb message
1490
1491    convenient function to turn a ldb_message into a string. Useful for
1492    debugging
1493  */
1494 char *ldb_ldif_message_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
1495                               enum ldb_changetype changetype,
1496                               const struct ldb_message *msg);
1497
1498
1499 /**
1500    Base64 encode a buffer
1501
1502    \param mem_ctx the memory context that the result is allocated
1503    from.
1504    \param buf pointer to the array that is to be encoded
1505    \param len the number of elements in the array to be encoded
1506
1507    \return pointer to an array containing the encoded data
1508
1509    \note The caller is responsible for freeing the result
1510 */
1511 char *ldb_base64_encode(TALLOC_CTX *mem_ctx, const char *buf, int len);
1512
1513 /**
1514    Base64 decode a buffer
1515
1516    This function decodes a base64 encoded string in place.
1517
1518    \param s the string to decode.
1519
1520    \return the length of the returned (decoded) string.
1521
1522    \note the string is null terminated, but the null terminator is not
1523    included in the length.
1524 */
1525 int ldb_base64_decode(char *s);
1526
1527 /* The following definitions come from lib/ldb/common/ldb_dn.c  */
1528
1529 /**
1530   Get the linear form of a DN (without any extended components)
1531
1532   \param dn The DN to linearize
1533 */
1534
1535 const char *ldb_dn_get_linearized(struct ldb_dn *dn);
1536
1537 /**
1538   Allocate a copy of the linear form of a DN (without any extended components) onto the supplied memory context
1539
1540   \param dn The DN to linearize
1541   \param mem_ctx TALLOC context to return result on
1542 */
1543
1544 char *ldb_dn_alloc_linearized(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1545
1546 /**
1547   Get the linear form of a DN (with any extended components)
1548
1549   \param mem_ctx TALLOC context to return result on
1550   \param dn The DN to linearize
1551   \param mode Style of extended DN to return (0 is HEX representation of binary form, 1 is a string form)
1552 */
1553 char *ldb_dn_get_extended_linearized(void *mem_ctx, struct ldb_dn *dn, int mode);
1554 const struct ldb_val *ldb_dn_get_extended_component(struct ldb_dn *dn, const char *name);
1555 int ldb_dn_set_extended_component(struct ldb_dn *dn, const char *name, const struct ldb_val *val);
1556
1557 void ldb_dn_remove_extended_components(struct ldb_dn *dn);
1558 bool ldb_dn_has_extended(struct ldb_dn *dn);
1559
1560 int ldb_dn_extended_add_syntax(struct ldb_context *ldb,
1561                                unsigned flags,
1562                                const struct ldb_dn_extended_syntax *syntax);
1563
1564 /**
1565   Allocate a new DN from a string
1566
1567   \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1568   \param dn The new DN
1569
1570   \note The DN will not be parsed at this time.  Use ldb_dn_validate to tell if the DN is syntacticly correct
1571 */
1572
1573 struct ldb_dn *ldb_dn_new(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *dn);
1574 /**
1575   Allocate a new DN from a printf style format string and arguments
1576
1577   \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1578   \param new_fms The new DN as a format string (plus arguments)
1579
1580   \note The DN will not be parsed at this time.  Use ldb_dn_validate to tell if the DN is syntacticly correct
1581 */
1582
1583 struct ldb_dn *ldb_dn_new_fmt(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *new_fmt, ...) PRINTF_ATTRIBUTE(3,4);
1584 /**
1585   Allocate a new DN from a struct ldb_val (useful to avoid buffer overrun)
1586
1587   \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1588   \param dn The new DN
1589
1590   \note The DN will not be parsed at this time.  Use ldb_dn_validate to tell if the DN is syntacticly correct
1591 */
1592
1593 struct ldb_dn *ldb_dn_from_ldb_val(void *mem_ctx, struct ldb_context *ldb, const struct ldb_val *strdn);
1594
1595 /**
1596   Determine if this DN is syntactically valid
1597
1598   \param dn The DN to validate
1599 */
1600
1601 bool ldb_dn_validate(struct ldb_dn *dn);
1602
1603 char *ldb_dn_escape_value(TALLOC_CTX *mem_ctx, struct ldb_val value);
1604 const char *ldb_dn_get_casefold(struct ldb_dn *dn);
1605 char *ldb_dn_alloc_casefold(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1606
1607 int ldb_dn_compare_base(struct ldb_dn *base, struct ldb_dn *dn);
1608 int ldb_dn_compare(struct ldb_dn *edn0, struct ldb_dn *edn1);
1609
1610 bool ldb_dn_add_base(struct ldb_dn *dn, struct ldb_dn *base);
1611 bool ldb_dn_add_base_fmt(struct ldb_dn *dn, const char *base_fmt, ...) PRINTF_ATTRIBUTE(2,3);
1612 bool ldb_dn_add_child(struct ldb_dn *dn, struct ldb_dn *child);
1613 bool ldb_dn_add_child_fmt(struct ldb_dn *dn, const char *child_fmt, ...) PRINTF_ATTRIBUTE(2,3);
1614 bool ldb_dn_remove_base_components(struct ldb_dn *dn, unsigned int num);
1615 bool ldb_dn_remove_child_components(struct ldb_dn *dn, unsigned int num);
1616
1617 struct ldb_dn *ldb_dn_copy(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1618 struct ldb_dn *ldb_dn_get_parent(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1619 char *ldb_dn_canonical_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1620 char *ldb_dn_canonical_ex_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1621 int ldb_dn_get_comp_num(struct ldb_dn *dn);
1622 const char *ldb_dn_get_component_name(struct ldb_dn *dn, unsigned int num);
1623 const struct ldb_val *ldb_dn_get_component_val(struct ldb_dn *dn, unsigned int num);
1624 const char *ldb_dn_get_rdn_name(struct ldb_dn *dn);
1625 const struct ldb_val *ldb_dn_get_rdn_val(struct ldb_dn *dn);
1626 int ldb_dn_set_component(struct ldb_dn *dn, int num, const char *name, const struct ldb_val val);
1627
1628 bool ldb_dn_is_valid(struct ldb_dn *dn);
1629 bool ldb_dn_is_special(struct ldb_dn *dn);
1630 bool ldb_dn_check_special(struct ldb_dn *dn, const char *check);
1631 bool ldb_dn_is_null(struct ldb_dn *dn);
1632
1633
1634 /**
1635    Compare two attributes
1636
1637    This function compares to attribute names. Note that this is a
1638    case-insensitive comparison.
1639
1640    \param a the first attribute name to compare
1641    \param b the second attribute name to compare
1642
1643    \return 0 if the attribute names are the same, or only differ in
1644    case; non-zero if there are any differences
1645
1646   attribute names are restricted by rfc2251 so using
1647   strcasecmp and toupper here is ok.
1648   return 0 for match
1649 */
1650 #define ldb_attr_cmp(a, b) strcasecmp(a, b)
1651 char *ldb_attr_casefold(TALLOC_CTX *mem_ctx, const char *s);
1652 int ldb_attr_dn(const char *attr);
1653
1654 /**
1655    Create an empty message
1656
1657    \param mem_ctx the memory context to create in. You can pass NULL
1658    to get the top level context, however the ldb context (from
1659    ldb_init()) may be a better choice
1660 */
1661 struct ldb_message *ldb_msg_new(TALLOC_CTX *mem_ctx);
1662
1663 /**
1664    Find an element within an message
1665 */
1666 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg,
1667                                                  const char *attr_name);
1668
1669 /**
1670    Compare two ldb_val values
1671
1672    \param v1 first ldb_val structure to be tested
1673    \param v2 second ldb_val structure to be tested
1674
1675    \return 1 for a match, 0 if there is any difference
1676 */
1677 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
1678
1679 /**
1680    find a value within an ldb_message_element
1681
1682    \param el the element to search
1683    \param val the value to search for
1684
1685    \note This search is case sensitive
1686 */
1687 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el,
1688                                  struct ldb_val *val);
1689
1690 /**
1691    add a new empty element to a ldb_message
1692 */
1693 int ldb_msg_add_empty(struct ldb_message *msg,
1694                 const char *attr_name,
1695                 int flags,
1696                 struct ldb_message_element **return_el);
1697
1698 /**
1699    add a element to a ldb_message
1700 */
1701 int ldb_msg_add(struct ldb_message *msg,
1702                 const struct ldb_message_element *el,
1703                 int flags);
1704 int ldb_msg_add_value(struct ldb_message *msg,
1705                 const char *attr_name,
1706                 const struct ldb_val *val,
1707                 struct ldb_message_element **return_el);
1708 int ldb_msg_add_steal_value(struct ldb_message *msg,
1709                       const char *attr_name,
1710                       struct ldb_val *val);
1711 int ldb_msg_add_steal_string(struct ldb_message *msg,
1712                              const char *attr_name, char *str);
1713 int ldb_msg_add_string(struct ldb_message *msg,
1714                        const char *attr_name, const char *str);
1715 int ldb_msg_add_fmt(struct ldb_message *msg,
1716                     const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
1717
1718 /**
1719    compare two message elements - return 0 on match
1720 */
1721 int ldb_msg_element_compare(struct ldb_message_element *el1,
1722                             struct ldb_message_element *el2);
1723 int ldb_msg_element_compare_name(struct ldb_message_element *el1,
1724                                  struct ldb_message_element *el2);
1725
1726 /**
1727    Find elements in a message.
1728
1729    This function finds elements and converts to a specific type, with
1730    a give default value if not found. Assumes that elements are
1731    single valued.
1732 */
1733 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
1734 int ldb_msg_find_attr_as_int(const struct ldb_message *msg,
1735                              const char *attr_name,
1736                              int default_value);
1737 unsigned int ldb_msg_find_attr_as_uint(const struct ldb_message *msg,
1738                                        const char *attr_name,
1739                                        unsigned int default_value);
1740 int64_t ldb_msg_find_attr_as_int64(const struct ldb_message *msg,
1741                                    const char *attr_name,
1742                                    int64_t default_value);
1743 uint64_t ldb_msg_find_attr_as_uint64(const struct ldb_message *msg,
1744                                      const char *attr_name,
1745                                      uint64_t default_value);
1746 double ldb_msg_find_attr_as_double(const struct ldb_message *msg,
1747                                    const char *attr_name,
1748                                    double default_value);
1749 int ldb_msg_find_attr_as_bool(const struct ldb_message *msg,
1750                               const char *attr_name,
1751                               int default_value);
1752 const char *ldb_msg_find_attr_as_string(const struct ldb_message *msg,
1753                                         const char *attr_name,
1754                                         const char *default_value);
1755
1756 struct ldb_dn *ldb_msg_find_attr_as_dn(struct ldb_context *ldb,
1757                                        TALLOC_CTX *mem_ctx,
1758                                        const struct ldb_message *msg,
1759                                        const char *attr_name);
1760
1761 void ldb_msg_sort_elements(struct ldb_message *msg);
1762
1763 struct ldb_message *ldb_msg_copy_shallow(TALLOC_CTX *mem_ctx,
1764                                          const struct ldb_message *msg);
1765 struct ldb_message *ldb_msg_copy(TALLOC_CTX *mem_ctx,
1766                                  const struct ldb_message *msg);
1767
1768 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb,
1769                                          const struct ldb_message *msg);
1770
1771
1772 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb,
1773                                  struct ldb_message *msg1,
1774                                  struct ldb_message *msg2);
1775
1776 int ldb_msg_check_string_attribute(const struct ldb_message *msg,
1777                                    const char *name,
1778                                    const char *value);
1779
1780 /**
1781    Integrity check an ldb_message
1782
1783    This function performs basic sanity / integrity checks on an
1784    ldb_message.
1785
1786    \param ldb context in which to perform the checks
1787    \param msg the message to check
1788
1789    \return LDB_SUCCESS if the message is OK, or a non-zero error code
1790    (one of LDB_ERR_INVALID_DN_SYNTAX, LDB_ERR_ENTRY_ALREADY_EXISTS or
1791    LDB_ERR_INVALID_ATTRIBUTE_SYNTAX) if there is a problem with a
1792    message.
1793 */
1794 int ldb_msg_sanity_check(struct ldb_context *ldb,
1795                          const struct ldb_message *msg);
1796
1797 /**
1798    Duplicate an ldb_val structure
1799
1800    This function copies an ldb value structure.
1801
1802    \param mem_ctx the memory context that the duplicated value will be
1803    allocated from
1804    \param v the ldb_val to be duplicated.
1805
1806    \return the duplicated ldb_val structure.
1807 */
1808 struct ldb_val ldb_val_dup(TALLOC_CTX *mem_ctx, const struct ldb_val *v);
1809
1810 /**
1811   this allows the user to set a debug function for error reporting
1812 */
1813 int ldb_set_debug(struct ldb_context *ldb,
1814                   void (*debug)(void *context, enum ldb_debug_level level,
1815                                 const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0),
1816                   void *context);
1817
1818 /**
1819   this allows the user to set custom utf8 function for error reporting
1820 */
1821 void ldb_set_utf8_fns(struct ldb_context *ldb,
1822                       void *context,
1823                       char *(*casefold)(void *, void *, const char *, size_t n));
1824
1825 /**
1826    this sets up debug to print messages on stderr
1827 */
1828 int ldb_set_debug_stderr(struct ldb_context *ldb);
1829
1830 /* control backend specific opaque values */
1831 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
1832 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
1833
1834 const char **ldb_attr_list_copy(TALLOC_CTX *mem_ctx, const char * const *attrs);
1835 const char **ldb_attr_list_copy_add(TALLOC_CTX *mem_ctx, const char * const *attrs, const char *new_attr);
1836 int ldb_attr_in_list(const char * const *attrs, const char *attr);
1837
1838 int ldb_msg_rename_attr(struct ldb_message *msg, const char *attr, const char *replace);
1839 int ldb_msg_copy_attr(struct ldb_message *msg, const char *attr, const char *replace);
1840 void ldb_msg_remove_attr(struct ldb_message *msg, const char *attr);
1841 void ldb_msg_remove_element(struct ldb_message *msg, struct ldb_message_element *el);
1842
1843
1844 void ldb_parse_tree_attr_replace(struct ldb_parse_tree *tree,
1845                                  const char *attr,
1846                                  const char *replace);
1847
1848 /*
1849   shallow copy a tree - copying only the elements array so that the caller
1850   can safely add new elements without changing the message
1851 */
1852 struct ldb_parse_tree *ldb_parse_tree_copy_shallow(TALLOC_CTX *mem_ctx,
1853                                                    const struct ldb_parse_tree *ot);
1854
1855 /**
1856    Convert a time structure to a string
1857
1858    This function converts a time_t structure to an LDAP formatted
1859    GeneralizedTime string.
1860
1861    \param mem_ctx the memory context to allocate the return string in
1862    \param t the time structure to convert
1863
1864    \return the formatted string, or NULL if the time structure could
1865    not be converted
1866 */
1867 char *ldb_timestring(TALLOC_CTX *mem_ctx, time_t t);
1868
1869 /**
1870    Convert a string to a time structure
1871
1872    This function converts an LDAP formatted GeneralizedTime string
1873    to a time_t structure.
1874
1875    \param s the string to convert
1876
1877    \return the time structure, or 0 if the string cannot be converted
1878 */
1879 time_t ldb_string_to_time(const char *s);
1880
1881 /**
1882    Convert a time structure to a string
1883
1884    This function converts a time_t structure to an LDAP formatted
1885    UTCTime string.
1886
1887    \param mem_ctx the memory context to allocate the return string in
1888    \param t the time structure to convert
1889
1890    \return the formatted string, or NULL if the time structure could
1891    not be converted
1892 */
1893 char *ldb_timestring_utc(TALLOC_CTX *mem_ctx, time_t t);
1894
1895 /**
1896    Convert a string to a time structure
1897
1898    This function converts an LDAP formatted UTCTime string
1899    to a time_t structure.
1900
1901    \param s the string to convert
1902
1903    \return the time structure, or 0 if the string cannot be converted
1904 */
1905 time_t ldb_string_utc_to_time(const char *s);
1906
1907
1908 void ldb_qsort (void *const pbase, size_t total_elems, size_t size, void *opaque, ldb_qsort_cmp_fn_t cmp);
1909
1910
1911 /**
1912    Convert an array of string represention of a control into an array of ldb_control structures
1913
1914    \param ldb LDB context
1915    \param mem_ctx TALLOC context to return result on, and to allocate error_string on
1916    \param control_strings Array of string-formatted controls
1917
1918    \return array of ldb_control elements
1919 */
1920 struct ldb_control **ldb_parse_control_strings(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char **control_strings);
1921
1922 /**
1923    return the ldb flags
1924 */
1925 unsigned int ldb_get_flags(struct ldb_context *ldb);
1926
1927 /* set the ldb flags */
1928 void ldb_set_flags(struct ldb_context *ldb, unsigned flags);
1929
1930
1931 #endif