lib/ldb/include/ldb_private.h

   1 /*
   2    ldb database library
   3
   4    Copyright (C) Andrew Tridgell    2004
   5    Copyright (C) Stefan Metzmacher  2004
   6    Copyright (C) Simo Sorce         2004-2005
   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 private header
  30  *
  31  *  Description: defines internal ldb structures used by the subsystem and modules
  32  *
  33  *  Author: Andrew Tridgell
  34  *  Author: Stefan Metzmacher
  35  */
  36
  37 #ifndef _LDB_PRIVATE_H_
  38 #define _LDB_PRIVATE_H_ 1
  39
  40 #include "replace.h"
  41 #include "system/filesys.h"
  42 #include "system/time.h"
  43 #include "ldb.h"
  44 #include "ldb_module.h"
  45
  46 struct ldb_context;
  47
  48 struct ldb_module_ops;
  49
  50 struct ldb_backend_ops;
  51
  52 #define LDB_HANDLE_FLAG_DONE_CALLED 1
  53 /* call is from an untrusted source - eg. over ldap:// */
  54 #define LDB_HANDLE_FLAG_UNTRUSTED   2
  55
  56 struct ldb_handle {
  57         int status;
  58         enum ldb_state state;
  59         struct ldb_context *ldb;
  60         unsigned flags;
  61         /* flags dedicated to be set by application using ldb */
  62         uint32_t custom_flags;
  63         unsigned nesting;
  64
  65         /* Private event context (if not NULL) */
  66         struct tevent_context *event_context;
  67
  68         /* used for debugging */
  69         struct ldb_request *parent;
  70         const char *location;
  71 };
  72
  73 /* basic module structure */
  74 struct ldb_module {
  75         struct ldb_module *prev, *next;
  76         struct ldb_context *ldb;
  77         void *private_data;
  78         const struct ldb_module_ops *ops;
  79 };
  80
  81 /*
  82   schema related information needed for matching rules
  83 */
  84 struct ldb_schema {
  85         void *attribute_handler_override_private;
  86         ldb_attribute_handler_override_fn_t attribute_handler_override;
  87
  88         /* attribute handling table */
  89         unsigned num_attributes;
  90         struct ldb_schema_attribute *attributes;
  91
  92         unsigned num_dn_extended_syntax;
  93         struct ldb_dn_extended_syntax *dn_extended_syntax;
  94
  95         /*
  96          * If set, the attribute_handler_override has the details of
  97          * what attributes have an index
  98          */
  99         bool index_handler_override;
 100         bool one_level_indexes;
 101
 102         const char *GUID_index_attribute;
 103         const char *GUID_index_dn_component;
 104 };
 105
 106 /**
 107   the user can optionally supply a debug function. The function
 108   is based on the vfprintf() style of interface, but with the addition
 109   of a severity level
 110 */
 111 struct ldb_debug_ops {
 112         void (*debug)(void *context, enum ldb_debug_level level,
 113                       const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0);
 114         void *context;
 115 };
 116
 117 /**
 118   The user can optionally supply a custom utf8 functions,
 119   to handle comparisons and casefolding.
 120 */
 121 struct ldb_utf8_fns {
 122         void *context;
 123         char *(*casefold)(void *context, TALLOC_CTX *mem_ctx, const char *s, size_t n);
 124         int (*casecmp)(void *context, const struct ldb_val *v1, const struct ldb_val *v2);
 125 };
 126
 127 /*
 128   every ldb connection is started by establishing a ldb_context
 129 */
 130 struct ldb_context {
 131         /* the operations provided by the backend */
 132         struct ldb_module *modules;
 133
 134         /* debugging operations */
 135         struct ldb_debug_ops debug_ops;
 136
 137         /* extended matching rules */
 138         struct ldb_extended_match_entry {
 139                 const struct ldb_extended_match_rule *rule;
 140                 struct ldb_extended_match_entry *prev, *next;
 141         } *extended_match_rules;
 142
 143         struct {
 144                 struct ldb_module *module;
 145                 ldb_redact_fn callback;
 146         } redact;
 147
 148         /* custom utf8 functions */
 149         struct ldb_utf8_fns utf8_fns;
 150
 151         /* backend specific opaque parameters */
 152         struct ldb_opaque {
 153                 struct ldb_opaque *next;
 154                 const char *name;
 155                 void *value;
 156         } *opaque;
 157
 158         struct ldb_schema schema;
 159
 160         char *err_string;
 161
 162         int transaction_active;
 163
 164         int default_timeout;
 165
 166         unsigned int flags;
 167
 168         unsigned int create_perms;
 169
 170         struct tevent_context *ev_ctx;
 171
 172         /*
 173          * If the backend holds locks, we must not use a global event
 174          * context, so this flag will be set and ldb_handle_new() will
 175          * build a new event context
 176          */
 177         bool require_private_event_context;
 178
 179         bool prepare_commit_done;
 180
 181         char *partial_debug;
 182
 183         struct poptOption *popt_options;
 184
 185         /*
 186          * The ldb options passed to ldb_connect
 187          * A NULL terminated array of zero terminated strings
 188          */
 189         const char **options;
 190 };
 191
 192 /* The following definitions come from lib/ldb/common/ldb.c  */
 193
 194 extern const struct ldb_module_ops ldb_objectclass_module_ops;
 195 extern const struct ldb_module_ops ldb_paged_results_module_ops;
 196 extern const struct ldb_module_ops ldb_rdn_name_module_ops;
 197 extern const struct ldb_module_ops ldb_schema_module_ops;
 198 extern const struct ldb_module_ops ldb_asq_module_ops;
 199 extern const struct ldb_module_ops ldb_server_sort_module_ops;
 200 extern const struct ldb_module_ops ldb_ldap_module_ops;
 201 extern const struct ldb_module_ops ldb_ildap_module_ops;
 202 extern const struct ldb_module_ops ldb_paged_searches_module_ops;
 203 extern const struct ldb_module_ops ldb_tdb_module_ops;
 204 extern const struct ldb_module_ops ldb_skel_module_ops;
 205 extern const struct ldb_module_ops ldb_subtree_rename_module_ops;
 206 extern const struct ldb_module_ops ldb_subtree_delete_module_ops;
 207 extern const struct ldb_module_ops ldb_sqlite3_module_ops;
 208 extern const struct ldb_module_ops ldb_wins_ldb_module_ops;
 209 extern const struct ldb_module_ops ldb_ranged_results_module_ops;
 210
 211 extern const struct ldb_backend_ops ldb_tdb_backend_ops;
 212 extern const struct ldb_backend_ops ldb_sqlite3_backend_ops;
 213 extern const struct ldb_backend_ops ldb_ldap_backend_ops;
 214 extern const struct ldb_backend_ops ldb_ldapi_backend_ops;
 215 extern const struct ldb_backend_ops ldb_ldaps_backend_ops;
 216
 217 int ldb_setup_wellknown_attributes(struct ldb_context *ldb);
 218 /*
 219   remove attributes with a specified flag (eg LDB_ATTR_FLAG_FROM_DB) for this ldb context
 220
 221   This is to permit correct reloads
 222 */
 223 void ldb_schema_attribute_remove_flagged(struct ldb_context *ldb, unsigned int flag);
 224 int ldb_schema_attribute_fill_with_syntax(struct ldb_context *ldb,
 225                                           TALLOC_CTX *mem_ctx,
 226                                           const char *attribute,
 227                                           unsigned flags,
 228                                           const struct ldb_schema_syntax *syntax,
 229                                           struct ldb_schema_attribute *a);
 230
 231 const char **ldb_subclass_list(struct ldb_context *ldb, const char *classname);
 232 void ldb_subclass_remove(struct ldb_context *ldb, const char *classname);
 233 int ldb_subclass_add(struct ldb_context *ldb, const char *classname, const char *subclass);
 234
 235 /* The following definitions come from lib/ldb/common/ldb_utf8.c */
 236 char *ldb_casefold_default(void *context, TALLOC_CTX *mem_ctx, const char *s, size_t n);
 237
 238 int ldb_comparison_fold_ascii(void *ignored,
 239                               const struct ldb_val *v1, const struct ldb_val *v2);
 240
 241 void ldb_dump_results(struct ldb_context *ldb, struct ldb_result *result, FILE *f);
 242
 243
 244 /* The following definitions come from lib/ldb/common/ldb_modules.c  */
 245
 246 const char **ldb_modules_list_from_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *string);
 247 int ldb_load_modules(struct ldb_context *ldb, const char *options[]);
 248
 249 struct ldb_val ldb_binary_decode(TALLOC_CTX *mem_ctx, const char *str);
 250
 251
 252 /* The following definitions come from lib/ldb/common/ldb_options.c  */
 253
 254 const char *ldb_options_find(struct ldb_context *ldb, const char *options[],
 255                              const char *option_name);
 256 const char **ldb_options_copy(TALLOC_CTX *ctx, const char *options[]);
 257
 258 /* The following definitions come from lib/ldb/common/ldb_ldif.c  */
 259
 260 struct ldif_read_file_state {
 261         FILE *f;
 262         size_t line_no;
 263 };
 264
 265 struct ldb_ldif *ldb_ldif_read_file_state(struct ldb_context *ldb,
 266                                           struct ldif_read_file_state *state);
 267
 268 char *ldb_ldif_write_redacted_trace_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
 269                                            const struct ldb_ldif *ldif);
 270
 271 /*
 272  * Get the LDB context in use on an LDB DN.
 273  *
 274  * This is helpful to the python LDB code, which may use as part of
 275  * adding base and child components to an existing DN.
 276  */
 277 struct ldb_context *ldb_dn_get_ldb_context(struct ldb_dn *dn);
 278
 279 #define LDB_MSG_FIND_COMMON_REMOVE_DUPLICATES 1
 280
 281 /**
 282   Determine whether any values in an element are also in another element,
 283   and optionally fix that.
 284
 285   \param ldb      an ldb context
 286   \param mem_ctx  a talloc context
 287   \param el       an element
 288   \param other_el another element
 289   \param options  flags controlling the function behaviour
 290
 291   Without the LDB_MSG_FIND_COMMON_REMOVE_DUPLICATES flag, return
 292   LDB_ERR_ATTRIBUTE_OR_VALUE_EXISTS if the elements share values, and
 293   LDB_SUCCESS if they don't. That is, determine whether there is an
 294   intersection without changing anything.
 295
 296   With the LDB_MSG_FIND_COMMON_REMOVE_DUPLICATES flag, any values in common
 297   are removed from the first element and LDB_SUCCESS is returned.
 298
 299   LDB_ERR_OPERATIONS_ERROR indicates an allocation failure or an unknown option.
 300   LDB_ERR_INAPPROPRIATE_MATCHING means the elements differ in name.
 301 */
 302
 303 int ldb_msg_find_common_values(struct ldb_context *ldb,
 304                                TALLOC_CTX *mem_ctx,
 305                                struct ldb_message_element *el,
 306                                struct ldb_message_element *other_el,
 307                                uint32_t options);
 308
 309 /**
 310    Detect whether an element contains duplicate values
 311
 312    \param ldb a currently unused ldb_context struct
 313    \param mem_ctx a talloc context
 314    \param el the element to search
 315    \param duplicate will point to a duplicate value if there are duplicates,
 316    or NULL otherwise.
 317    \param options is a flags field. All values are reserved.
 318
 319    \return an ldb error code. LDB_ERR_OPERATIONS_ERROR indicates an allocation
 320    failure or an unknown option flag. Otherwise LDB_SUCCESS.
 321
 322    \note This search is case sensitive
 323 */
 324 int ldb_msg_find_duplicate_val(struct ldb_context *ldb,
 325                                TALLOC_CTX *mem_ctx,
 326                                const struct ldb_message_element *el,
 327                                struct ldb_val **duplicate,
 328                                uint32_t options);
 329 /**
 330   Check if a particular message will match the given filter
 331
 332   \param ldb an ldb context
 333   \param msg the message to be checked
 334   \param tree the filter tree to check against
 335   \param scope the scope to match against
 336          (to avoid matching special DNs except on a base search)
 337   \param matched a pointer to a boolean set true if it matches,
 338          false otherwise
 339
 340   returns LDB_SUCCESS or an error
 341
 342   \note this is a recursive function, and does short-circuit evaluation
 343  */
 344 int ldb_match_message(struct ldb_context *ldb,
 345                       const struct ldb_message *msg,
 346                       const struct ldb_parse_tree *tree,
 347                       enum ldb_scope scope, bool *matched);
 348
 349 /*
 350   check if the scope matches in a search result
 351 */
 352 int ldb_match_scope(struct ldb_context *ldb,
 353                     struct ldb_dn *base,
 354                     struct ldb_dn *dn,
 355                     enum ldb_scope scope);
 356
 357 /* Reallocate elements to drop any excess capacity. */
 358 void ldb_msg_shrink_to_fit(struct ldb_message *msg);
 359
 360 /*
 361   add the special distinguishedName element
 362 */
 363 int ldb_msg_add_distinguished_name(struct ldb_message *msg);
 364
 365 /**
 366  * @brief Convert a character to uppercase with ASCII precedence.
 367  *
 368  * This will convert a character to uppercase. If the character is an ASCII
 369  * character it will convert it to uppercase ASCII first and then fallback to
 370  * localized toupper() from libc.
 371  *
 372  * @param c The character to convert.
 373  *
 374  * @return The converted character or c if the conversion was not possible.
 375  */
 376 char ldb_ascii_toupper(char c);
 377
 378 #endif