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