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