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   commit a transaction
1288 */
1289 int ldb_transaction_commit(struct ldb_context *ldb);
1290
1291 /**
1292   cancel a transaction
1293 */
1294 int ldb_transaction_cancel(struct ldb_context *ldb);
1295
1296
1297 /**
1298   return extended error information from the last call
1299 */
1300 const char *ldb_errstring(struct ldb_context *ldb);
1301
1302 /**
1303   return a string explaining what a ldb error constant meancs
1304 */
1305 const char *ldb_strerror(int ldb_err);
1306
1307 /**
1308   setup the default utf8 functions
1309   FIXME: these functions do not yet handle utf8
1310 */
1311 void ldb_set_utf8_default(struct ldb_context *ldb);
1312
1313 /**
1314    Casefold a string
1315
1316    \param ldb the ldb context
1317    \param mem_ctx the memory context to allocate the result string
1318    memory from.
1319    \param s the string that is to be folded
1320    \return a copy of the string, converted to upper case
1321
1322    \note The default function is not yet UTF8 aware. Provide your own
1323          set of functions through ldb_set_utf8_fns()
1324 */
1325 char *ldb_casefold(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *s, size_t n);
1326
1327 /**
1328    Check the attribute name is valid according to rfc2251
1329    \param s the string to check
1330
1331    \return 1 if the name is ok
1332 */
1333 int ldb_valid_attr_name(const char *s);
1334
1335 /*
1336   ldif manipulation functions
1337 */
1338
1339 /**
1340    Write an LDIF message
1341
1342    This function writes an LDIF message using a caller supplied  write
1343    function.
1344
1345    \param ldb the ldb context (from ldb_init())
1346    \param fprintf_fn a function pointer for the write function. This must take
1347    a private data pointer, followed by a format string, and then a variable argument
1348    list.
1349    \param private_data pointer that will be provided back to the write
1350    function. This is useful for maintaining state or context.
1351    \param ldif the message to write out
1352
1353    \return the total number of bytes written, or an error code as returned
1354    from the write function.
1355
1356    \sa ldb_ldif_write_file for a more convenient way to write to a
1357    file stream.
1358
1359    \sa ldb_ldif_read for the reader equivalent to this function.
1360 */
1361 int ldb_ldif_write(struct ldb_context *ldb,
1362                    int (*fprintf_fn)(void *, const char *, ...) PRINTF_ATTRIBUTE(2,3),
1363                    void *private_data,
1364                    const struct ldb_ldif *ldif);
1365
1366 /**
1367    Clean up an LDIF message
1368
1369    This function cleans up a LDIF message read using ldb_ldif_read()
1370    or related functions (such as ldb_ldif_read_string() and
1371    ldb_ldif_read_file().
1372
1373    \param ldb the ldb context (from ldb_init())
1374    \param msg the message to clean up and free
1375
1376 */
1377 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *msg);
1378
1379 /**
1380    Read an LDIF message
1381
1382    This function creates an LDIF message using a caller supplied read
1383    function.
1384
1385    \param ldb the ldb context (from ldb_init())
1386    \param fgetc_fn a function pointer for the read function. This must
1387    take a private data pointer, and must return a pointer to an
1388    integer corresponding to the next byte read (or EOF if there is no
1389    more data to be read).
1390    \param private_data pointer that will be provided back to the read
1391    function. This is udeful for maintaining state or context.
1392
1393    \return the LDIF message that has been read in
1394
1395    \note You must free the LDIF message when no longer required, using
1396    ldb_ldif_read_free().
1397
1398    \sa ldb_ldif_read_file for a more convenient way to read from a
1399    file stream.
1400
1401    \sa ldb_ldif_read_string for a more convenient way to read from a
1402    string (char array).
1403
1404    \sa ldb_ldif_write for the writer equivalent to this function.
1405 */
1406 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
1407                                int (*fgetc_fn)(void *), void *private_data);
1408
1409 /**
1410    Read an LDIF message from a file
1411
1412    This function reads the next LDIF message from the contents of a
1413    file stream. If you want to get all of the LDIF messages, you will
1414    need to repeatedly call this function, until it returns NULL.
1415
1416    \param ldb the ldb context (from ldb_init())
1417    \param f the file stream to read from (typically from fdopen())
1418
1419    \sa ldb_ldif_read_string for an equivalent function that will read
1420    from a string (char array).
1421
1422    \sa ldb_ldif_write_file for the writer equivalent to this function.
1423
1424 */
1425 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
1426
1427 /**
1428    Read an LDIF message from a string
1429
1430    This function reads the next LDIF message from the contents of a char
1431    array. If you want to get all of the LDIF messages, you will need
1432    to repeatedly call this function, until it returns NULL.
1433
1434    \param ldb the ldb context (from ldb_init())
1435    \param s pointer to the char array to read from
1436
1437    \sa ldb_ldif_read_file for an equivalent function that will read
1438    from a file stream.
1439
1440    \sa ldb_ldif_write for a more general (arbitrary read function)
1441    version of this function.
1442 */
1443 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
1444
1445 /**
1446    Write an LDIF message to a file
1447
1448    \param ldb the ldb context (from ldb_init())
1449    \param f the file stream to write to (typically from fdopen())
1450    \param msg the message to write out
1451
1452    \return the total number of bytes written, or a negative error code
1453
1454    \sa ldb_ldif_read_file for the reader equivalent to this function.
1455 */
1456 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
1457
1458 /**
1459    Write an LDIF message to a string
1460
1461    \param ldb the ldb context (from ldb_init())
1462    \param mem_ctx the talloc context on which to attach the string)
1463    \param msg the message to write out
1464
1465    \return the string containing the LDIF, or NULL on error
1466
1467    \sa ldb_ldif_read_string for the reader equivalent to this function.
1468 */
1469 char * ldb_ldif_write_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
1470                           const struct ldb_ldif *msg);
1471
1472
1473 /*
1474    Produce a string form of an ldb message
1475
1476    convenient function to turn a ldb_message into a string. Useful for
1477    debugging
1478  */
1479 char *ldb_ldif_message_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
1480                               enum ldb_changetype changetype,
1481                               const struct ldb_message *msg);
1482
1483
1484 /**
1485    Base64 encode a buffer
1486
1487    \param mem_ctx the memory context that the result is allocated
1488    from.
1489    \param buf pointer to the array that is to be encoded
1490    \param len the number of elements in the array to be encoded
1491
1492    \return pointer to an array containing the encoded data
1493
1494    \note The caller is responsible for freeing the result
1495 */
1496 char *ldb_base64_encode(TALLOC_CTX *mem_ctx, const char *buf, int len);
1497
1498 /**
1499    Base64 decode a buffer
1500
1501    This function decodes a base64 encoded string in place.
1502
1503    \param s the string to decode.
1504
1505    \return the length of the returned (decoded) string.
1506
1507    \note the string is null terminated, but the null terminator is not
1508    included in the length.
1509 */
1510 int ldb_base64_decode(char *s);
1511
1512 /* The following definitions come from lib/ldb/common/ldb_dn.c  */
1513
1514 /**
1515   Get the linear form of a DN (without any extended components)
1516
1517   \param dn The DN to linearize
1518 */
1519
1520 const char *ldb_dn_get_linearized(struct ldb_dn *dn);
1521
1522 /**
1523   Allocate a copy of the linear form of a DN (without any extended components) onto the supplied memory context
1524
1525   \param dn The DN to linearize
1526   \param mem_ctx TALLOC context to return result on
1527 */
1528
1529 char *ldb_dn_alloc_linearized(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1530
1531 /**
1532   Get the linear form of a DN (with any extended components)
1533
1534   \param mem_ctx TALLOC context to return result on
1535   \param dn The DN to linearize
1536   \param mode Style of extended DN to return (0 is HEX representation of binary form, 1 is a string form)
1537 */
1538 char *ldb_dn_get_extended_linearized(void *mem_ctx, struct ldb_dn *dn, int mode);
1539 const struct ldb_val *ldb_dn_get_extended_component(struct ldb_dn *dn, const char *name);
1540 int ldb_dn_set_extended_component(struct ldb_dn *dn, const char *name, const struct ldb_val *val);
1541
1542 void ldb_dn_remove_extended_components(struct ldb_dn *dn);
1543 bool ldb_dn_has_extended(struct ldb_dn *dn);
1544
1545 int ldb_dn_extended_add_syntax(struct ldb_context *ldb,
1546                                unsigned flags,
1547                                const struct ldb_dn_extended_syntax *syntax);
1548
1549 /**
1550   Allocate a new DN from a string
1551
1552   \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1553   \param dn The new DN
1554
1555   \note The DN will not be parsed at this time.  Use ldb_dn_validate to tell if the DN is syntacticly correct
1556 */
1557
1558 struct ldb_dn *ldb_dn_new(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *dn);
1559 /**
1560   Allocate a new DN from a printf style format string and arguments
1561
1562   \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1563   \param new_fms The new DN as a format string (plus arguments)
1564
1565   \note The DN will not be parsed at this time.  Use ldb_dn_validate to tell if the DN is syntacticly correct
1566 */
1567
1568 struct ldb_dn *ldb_dn_new_fmt(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *new_fmt, ...) PRINTF_ATTRIBUTE(3,4);
1569 /**
1570   Allocate a new DN from a struct ldb_val (useful to avoid buffer overrun)
1571
1572   \param mem_ctx TALLOC context to return resulting ldb_dn structure on
1573   \param dn The new DN
1574
1575   \note The DN will not be parsed at this time.  Use ldb_dn_validate to tell if the DN is syntacticly correct
1576 */
1577
1578 struct ldb_dn *ldb_dn_from_ldb_val(void *mem_ctx, struct ldb_context *ldb, const struct ldb_val *strdn);
1579
1580 /**
1581   Determine if this DN is syntactically valid
1582
1583   \param dn The DN to validate
1584 */
1585
1586 bool ldb_dn_validate(struct ldb_dn *dn);
1587
1588 char *ldb_dn_escape_value(TALLOC_CTX *mem_ctx, struct ldb_val value);
1589 const char *ldb_dn_get_casefold(struct ldb_dn *dn);
1590 char *ldb_dn_alloc_casefold(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1591
1592 int ldb_dn_compare_base(struct ldb_dn *base, struct ldb_dn *dn);
1593 int ldb_dn_compare(struct ldb_dn *edn0, struct ldb_dn *edn1);
1594
1595 bool ldb_dn_add_base(struct ldb_dn *dn, struct ldb_dn *base);
1596 bool ldb_dn_add_base_fmt(struct ldb_dn *dn, const char *base_fmt, ...) PRINTF_ATTRIBUTE(2,3);
1597 bool ldb_dn_add_child(struct ldb_dn *dn, struct ldb_dn *child);
1598 bool ldb_dn_add_child_fmt(struct ldb_dn *dn, const char *child_fmt, ...) PRINTF_ATTRIBUTE(2,3);
1599 bool ldb_dn_remove_base_components(struct ldb_dn *dn, unsigned int num);
1600 bool ldb_dn_remove_child_components(struct ldb_dn *dn, unsigned int num);
1601
1602 struct ldb_dn *ldb_dn_copy(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1603 struct ldb_dn *ldb_dn_get_parent(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1604 char *ldb_dn_canonical_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1605 char *ldb_dn_canonical_ex_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
1606 int ldb_dn_get_comp_num(struct ldb_dn *dn);
1607 const char *ldb_dn_get_component_name(struct ldb_dn *dn, unsigned int num);
1608 const struct ldb_val *ldb_dn_get_component_val(struct ldb_dn *dn, unsigned int num);
1609 const char *ldb_dn_get_rdn_name(struct ldb_dn *dn);
1610 const struct ldb_val *ldb_dn_get_rdn_val(struct ldb_dn *dn);
1611 int ldb_dn_set_component(struct ldb_dn *dn, int num, const char *name, const struct ldb_val val);
1612
1613 bool ldb_dn_is_valid(struct ldb_dn *dn);
1614 bool ldb_dn_is_special(struct ldb_dn *dn);
1615 bool ldb_dn_check_special(struct ldb_dn *dn, const char *check);
1616 bool ldb_dn_is_null(struct ldb_dn *dn);
1617
1618
1619 /**
1620    Compare two attributes
1621
1622    This function compares to attribute names. Note that this is a
1623    case-insensitive comparison.
1624
1625    \param a the first attribute name to compare
1626    \param b the second attribute name to compare
1627
1628    \return 0 if the attribute names are the same, or only differ in
1629    case; non-zero if there are any differences
1630
1631   attribute names are restricted by rfc2251 so using
1632   strcasecmp and toupper here is ok.
1633   return 0 for match
1634 */
1635 #define ldb_attr_cmp(a, b) strcasecmp(a, b)
1636 char *ldb_attr_casefold(TALLOC_CTX *mem_ctx, const char *s);
1637 int ldb_attr_dn(const char *attr);
1638
1639 /**
1640    Create an empty message
1641
1642    \param mem_ctx the memory context to create in. You can pass NULL
1643    to get the top level context, however the ldb context (from
1644    ldb_init()) may be a better choice
1645 */
1646 struct ldb_message *ldb_msg_new(TALLOC_CTX *mem_ctx);
1647
1648 /**
1649    Find an element within an message
1650 */
1651 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg,
1652                                                  const char *attr_name);
1653
1654 /**
1655    Compare two ldb_val values
1656
1657    \param v1 first ldb_val structure to be tested
1658    \param v2 second ldb_val structure to be tested
1659
1660    \return 1 for a match, 0 if there is any difference
1661 */
1662 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
1663
1664 /**
1665    find a value within an ldb_message_element
1666
1667    \param el the element to search
1668    \param val the value to search for
1669
1670    \note This search is case sensitive
1671 */
1672 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el,
1673                                  struct ldb_val *val);
1674
1675 /**
1676    add a new empty element to a ldb_message
1677 */
1678 int ldb_msg_add_empty(struct ldb_message *msg,
1679                 const char *attr_name,
1680                 int flags,
1681                 struct ldb_message_element **return_el);
1682
1683 /**
1684    add a element to a ldb_message
1685 */
1686 int ldb_msg_add(struct ldb_message *msg,
1687                 const struct ldb_message_element *el,
1688                 int flags);
1689 int ldb_msg_add_value(struct ldb_message *msg,
1690                 const char *attr_name,
1691                 const struct ldb_val *val,
1692                 struct ldb_message_element **return_el);
1693 int ldb_msg_add_steal_value(struct ldb_message *msg,
1694                       const char *attr_name,
1695                       struct ldb_val *val);
1696 int ldb_msg_add_steal_string(struct ldb_message *msg,
1697                              const char *attr_name, char *str);
1698 int ldb_msg_add_string(struct ldb_message *msg,
1699                        const char *attr_name, const char *str);
1700 int ldb_msg_add_fmt(struct ldb_message *msg,
1701                     const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
1702
1703 /**
1704    compare two message elements - return 0 on match
1705 */
1706 int ldb_msg_element_compare(struct ldb_message_element *el1,
1707                             struct ldb_message_element *el2);
1708 int ldb_msg_element_compare_name(struct ldb_message_element *el1,
1709                                  struct ldb_message_element *el2);
1710
1711 /**
1712    Find elements in a message.
1713
1714    This function finds elements and converts to a specific type, with
1715    a give default value if not found. Assumes that elements are
1716    single valued.
1717 */
1718 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
1719 int ldb_msg_find_attr_as_int(const struct ldb_message *msg,
1720                              const char *attr_name,
1721                              int default_value);
1722 unsigned int ldb_msg_find_attr_as_uint(const struct ldb_message *msg,
1723                                        const char *attr_name,
1724                                        unsigned int default_value);
1725 int64_t ldb_msg_find_attr_as_int64(const struct ldb_message *msg,
1726                                    const char *attr_name,
1727                                    int64_t default_value);
1728 uint64_t ldb_msg_find_attr_as_uint64(const struct ldb_message *msg,
1729                                      const char *attr_name,
1730                                      uint64_t default_value);
1731 double ldb_msg_find_attr_as_double(const struct ldb_message *msg,
1732                                    const char *attr_name,
1733                                    double default_value);
1734 int ldb_msg_find_attr_as_bool(const struct ldb_message *msg,
1735                               const char *attr_name,
1736                               int default_value);
1737 const char *ldb_msg_find_attr_as_string(const struct ldb_message *msg,
1738                                         const char *attr_name,
1739                                         const char *default_value);
1740
1741 struct ldb_dn *ldb_msg_find_attr_as_dn(struct ldb_context *ldb,
1742                                        TALLOC_CTX *mem_ctx,
1743                                        const struct ldb_message *msg,
1744                                        const char *attr_name);
1745
1746 void ldb_msg_sort_elements(struct ldb_message *msg);
1747
1748 struct ldb_message *ldb_msg_copy_shallow(TALLOC_CTX *mem_ctx,
1749                                          const struct ldb_message *msg);
1750 struct ldb_message *ldb_msg_copy(TALLOC_CTX *mem_ctx,
1751                                  const struct ldb_message *msg);
1752
1753 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb,
1754                                          const struct ldb_message *msg);
1755
1756
1757 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb,
1758                                  struct ldb_message *msg1,
1759                                  struct ldb_message *msg2);
1760
1761 int ldb_msg_check_string_attribute(const struct ldb_message *msg,
1762                                    const char *name,
1763                                    const char *value);
1764
1765 /**
1766    Integrity check an ldb_message
1767
1768    This function performs basic sanity / integrity checks on an
1769    ldb_message.
1770
1771    \param ldb context in which to perform the checks
1772    \param msg the message to check
1773
1774    \return LDB_SUCCESS if the message is OK, or a non-zero error code
1775    (one of LDB_ERR_INVALID_DN_SYNTAX, LDB_ERR_ENTRY_ALREADY_EXISTS or
1776    LDB_ERR_INVALID_ATTRIBUTE_SYNTAX) if there is a problem with a
1777    message.
1778 */
1779 int ldb_msg_sanity_check(struct ldb_context *ldb,
1780                          const struct ldb_message *msg);
1781
1782 /**
1783    Duplicate an ldb_val structure
1784
1785    This function copies an ldb value structure.
1786
1787    \param mem_ctx the memory context that the duplicated value will be
1788    allocated from
1789    \param v the ldb_val to be duplicated.
1790
1791    \return the duplicated ldb_val structure.
1792 */
1793 struct ldb_val ldb_val_dup(TALLOC_CTX *mem_ctx, const struct ldb_val *v);
1794
1795 /**
1796   this allows the user to set a debug function for error reporting
1797 */
1798 int ldb_set_debug(struct ldb_context *ldb,
1799                   void (*debug)(void *context, enum ldb_debug_level level,
1800                                 const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0),
1801                   void *context);
1802
1803 /**
1804   this allows the user to set custom utf8 function for error reporting
1805 */
1806 void ldb_set_utf8_fns(struct ldb_context *ldb,
1807                       void *context,
1808                       char *(*casefold)(void *, void *, const char *, size_t n));
1809
1810 /**
1811    this sets up debug to print messages on stderr
1812 */
1813 int ldb_set_debug_stderr(struct ldb_context *ldb);
1814
1815 /* control backend specific opaque values */
1816 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
1817 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
1818
1819 const char **ldb_attr_list_copy(TALLOC_CTX *mem_ctx, const char * const *attrs);
1820 const char **ldb_attr_list_copy_add(TALLOC_CTX *mem_ctx, const char * const *attrs, const char *new_attr);
1821 int ldb_attr_in_list(const char * const *attrs, const char *attr);
1822
1823 int ldb_msg_rename_attr(struct ldb_message *msg, const char *attr, const char *replace);
1824 int ldb_msg_copy_attr(struct ldb_message *msg, const char *attr, const char *replace);
1825 void ldb_msg_remove_attr(struct ldb_message *msg, const char *attr);
1826 void ldb_msg_remove_element(struct ldb_message *msg, struct ldb_message_element *el);
1827
1828
1829 void ldb_parse_tree_attr_replace(struct ldb_parse_tree *tree,
1830                                  const char *attr,
1831                                  const char *replace);
1832
1833
1834 /**
1835    Convert a time structure to a string
1836
1837    This function converts a time_t structure to an LDAP formatted
1838    GeneralizedTime string.
1839
1840    \param mem_ctx the memory context to allocate the return string in
1841    \param t the time structure to convert
1842
1843    \return the formatted string, or NULL if the time structure could
1844    not be converted
1845 */
1846 char *ldb_timestring(TALLOC_CTX *mem_ctx, time_t t);
1847
1848 /**
1849    Convert a string to a time structure
1850
1851    This function converts an LDAP formatted GeneralizedTime string
1852    to a time_t structure.
1853
1854    \param s the string to convert
1855
1856    \return the time structure, or 0 if the string cannot be converted
1857 */
1858 time_t ldb_string_to_time(const char *s);
1859
1860 /**
1861    Convert a time structure to a string
1862
1863    This function converts a time_t structure to an LDAP formatted
1864    UTCTime string.
1865
1866    \param mem_ctx the memory context to allocate the return string in
1867    \param t the time structure to convert
1868
1869    \return the formatted string, or NULL if the time structure could
1870    not be converted
1871 */
1872 char *ldb_timestring_utc(TALLOC_CTX *mem_ctx, time_t t);
1873
1874 /**
1875    Convert a string to a time structure
1876
1877    This function converts an LDAP formatted UTCTime string
1878    to a time_t structure.
1879
1880    \param s the string to convert
1881
1882    \return the time structure, or 0 if the string cannot be converted
1883 */
1884 time_t ldb_string_utc_to_time(const char *s);
1885
1886
1887 void ldb_qsort (void *const pbase, size_t total_elems, size_t size, void *opaque, ldb_qsort_cmp_fn_t cmp);
1888
1889
1890 /**
1891    Convert an array of string represention of a control into an array of ldb_control structures
1892
1893    \param ldb LDB context
1894    \param mem_ctx TALLOC context to return result on, and to allocate error_string on
1895    \param control_strings Array of string-formatted controls
1896
1897    \return array of ldb_control elements
1898 */
1899 struct ldb_control **ldb_parse_control_strings(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char **control_strings);
1900
1901 #endif