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