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