source4/lib/ldb/include/ldb_module.h

   1 /*
   2    ldb database library
   3
   4    Copyright (C) Simo Sorce         2008
   5
   6      ** NOTE! The following LGPL license applies to the ldb
   7      ** library. This does NOT imply that all of Samba is released
   8      ** under the LGPL
   9
  10    This library is free software; you can redistribute it and/or
  11    modify it under the terms of the GNU Lesser General Public
  12    License as published by the Free Software Foundation; either
  13    version 3 of the License, or (at your option) any later version.
  14
  15    This library is distributed in the hope that it will be useful,
  16    but WITHOUT ANY WARRANTY; without even the implied warranty of
  17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18    Lesser General Public License for more details.
  19
  20    You should have received a copy of the GNU Lesser General Public
  21    License along with this library; if not, see <http://www.gnu.org/licenses/>.
  22 */
  23
  24 /*
  25  *  Name: ldb
  26  *
  27  *  Component: ldb module header
  28  *
  29  *  Description: defines ldb modules structures and helpers
  30  *
  31  */
  32
  33 #ifndef _LDB_MODULE_H_
  34 #define _LDB_MODULE_H_
  35
  36 #include "ldb.h"
  37
  38 struct ldb_context;
  39 struct ldb_module;
  40
  41 /**
  42    internal flag bits on message elements. Must be within LDB_FLAG_INTERNAL_MASK
  43  */
  44 #define LDB_FLAG_INTERNAL_DISABLE_VALIDATION 0x10
  45
  46
  47 /*
  48    these function pointers define the operations that a ldb module can intercept
  49 */
  50 struct ldb_module_ops {
  51         const char *name;
  52         int (*init_context) (struct ldb_module *);
  53         int (*search)(struct ldb_module *, struct ldb_request *); /* search */
  54         int (*add)(struct ldb_module *, struct ldb_request *); /* add */
  55         int (*modify)(struct ldb_module *, struct ldb_request *); /* modify */
  56         int (*del)(struct ldb_module *, struct ldb_request *); /* delete */
  57         int (*rename)(struct ldb_module *, struct ldb_request *); /* rename */
  58         int (*request)(struct ldb_module *, struct ldb_request *); /* match any other operation */
  59         int (*extended)(struct ldb_module *, struct ldb_request *); /* extended operations */
  60         int (*start_transaction)(struct ldb_module *);
  61         int (*prepare_commit)(struct ldb_module *);
  62         int (*end_transaction)(struct ldb_module *);
  63         int (*del_transaction)(struct ldb_module *);
  64         int (*sequence_number)(struct ldb_module *, struct ldb_request *);
  65         void *private_data;
  66 };
  67
  68
  69 /* The following definitions come from lib/ldb/common/ldb_debug.c  */
  70 void ldb_debug(struct ldb_context *ldb, enum ldb_debug_level level, const char *fmt, ...) PRINTF_ATTRIBUTE(3, 4);
  71 void ldb_debug_set(struct ldb_context *ldb, enum ldb_debug_level level,
  72                    const char *fmt, ...) PRINTF_ATTRIBUTE(3, 4);
  73 void ldb_debug_add(struct ldb_context *ldb, const char *fmt, ...) PRINTF_ATTRIBUTE(2, 3);
  74 void ldb_debug_end(struct ldb_context *ldb, enum ldb_debug_level level);
  75
  76 #define ldb_error(ldb, ecode, reason) ldb_error_at(ldb, ecode, reason, __FILE__, __LINE__)
  77
  78 #define ldb_oom(ldb) ldb_error(ldb, LDB_ERR_OPERATIONS_ERROR, "ldb out of memory")
  79 #define ldb_module_oom(module) ldb_oom(ldb_module_get_ctx(module))
  80 #define ldb_operr(ldb) ldb_error(ldb, LDB_ERR_OPERATIONS_ERROR, "operations error")
  81
  82 /* The following definitions come from lib/ldb/common/ldb.c  */
  83
  84 void ldb_request_set_state(struct ldb_request *req, int state);
  85 int ldb_request_get_status(struct ldb_request *req);
  86
  87 unsigned int ldb_get_create_perms(struct ldb_context *ldb);
  88
  89 const struct ldb_schema_syntax *ldb_standard_syntax_by_name(struct ldb_context *ldb,
  90                                                             const char *syntax);
  91
  92 /* The following definitions come from lib/ldb/common/ldb_attributes.c  */
  93
  94 int ldb_schema_attribute_add_with_syntax(struct ldb_context *ldb,
  95                                          const char *name,
  96                                          unsigned flags,
  97                                          const struct ldb_schema_syntax *syntax);
  98 int ldb_schema_attribute_add(struct ldb_context *ldb,
  99                              const char *name,
 100                              unsigned flags,
 101                              const char *syntax);
 102 void ldb_schema_attribute_remove(struct ldb_context *ldb, const char *name);
 103
 104 /* we allow external code to override the name -> schema_attribute function */
 105 typedef const struct ldb_schema_attribute *(*ldb_attribute_handler_override_fn_t)(struct ldb_context *, void *, const char *);
 106
 107 void ldb_schema_attribute_set_override_handler(struct ldb_context *ldb,
 108                                                ldb_attribute_handler_override_fn_t override,
 109                                                void *private_data);
 110
 111 /* A useful function to build comparison functions with */
 112 int ldb_any_comparison(struct ldb_context *ldb, void *mem_ctx,
 113                        ldb_attr_handler_t canonicalise_fn,
 114                        const struct ldb_val *v1,
 115                        const struct ldb_val *v2);
 116
 117 /* The following definitions come from lib/ldb/common/ldb_controls.c  */
 118 struct ldb_control *get_control_from_list(struct ldb_control **controls, const char *oid);
 119 int save_controls(struct ldb_control *exclude, struct ldb_request *req, struct ldb_control ***saver);
 120 /* Returns a list of controls, except the one specified.  Included
 121  * controls become a child of returned list if they were children of
 122  * controls_in */
 123 struct ldb_control **controls_except_specified(struct ldb_control **controls_in,
 124                                                TALLOC_CTX *mem_ctx,
 125                                                struct ldb_control *exclude);
 126 int check_critical_controls(struct ldb_control **controls);
 127
 128 /* The following definitions come from lib/ldb/common/ldb_ldif.c  */
 129 int ldb_should_b64_encode(struct ldb_context *ldb, const struct ldb_val *val);
 130
 131 /* The following definitions come from lib/ldb/common/ldb_match.c  */
 132 int ldb_match_msg(struct ldb_context *ldb,
 133                   const struct ldb_message *msg,
 134                   const struct ldb_parse_tree *tree,
 135                   struct ldb_dn *base,
 136                   enum ldb_scope scope);
 137
 138 int ldb_match_msg_error(struct ldb_context *ldb,
 139                         const struct ldb_message *msg,
 140                         const struct ldb_parse_tree *tree,
 141                         struct ldb_dn *base,
 142                         enum ldb_scope scope,
 143                         bool *matched);
 144
 145 int ldb_match_msg_objectclass(const struct ldb_message *msg,
 146                               const char *objectclass);
 147
 148 /* The following definitions come from lib/ldb/common/ldb_modules.c  */
 149
 150 struct ldb_module *ldb_module_new(TALLOC_CTX *memctx,
 151                                   struct ldb_context *ldb,
 152                                   const char *module_name,
 153                                   const struct ldb_module_ops *ops);
 154
 155 const char * ldb_module_get_name(struct ldb_module *module);
 156 struct ldb_context *ldb_module_get_ctx(struct ldb_module *module);
 157 void *ldb_module_get_private(struct ldb_module *module);
 158 void ldb_module_set_private(struct ldb_module *module, void *private_data);
 159 const struct ldb_module_ops *ldb_module_get_ops(struct ldb_module *module);
 160
 161 int ldb_next_request(struct ldb_module *module, struct ldb_request *request);
 162 int ldb_next_start_trans(struct ldb_module *module);
 163 int ldb_next_end_trans(struct ldb_module *module);
 164 int ldb_next_del_trans(struct ldb_module *module);
 165 int ldb_next_prepare_commit(struct ldb_module *module);
 166 int ldb_next_init(struct ldb_module *module);
 167
 168 void ldb_set_errstring(struct ldb_context *ldb, const char *err_string);
 169 void ldb_asprintf_errstring(struct ldb_context *ldb, const char *format, ...) PRINTF_ATTRIBUTE(2,3);
 170 void ldb_reset_err_string(struct ldb_context *ldb);
 171 int ldb_error_at(struct ldb_context *ldb, int ecode, const char *reason, const char *file, int line);
 172
 173 const char *ldb_default_modules_dir(void);
 174
 175 int ldb_register_module(const struct ldb_module_ops *);
 176
 177 typedef int (*ldb_connect_fn)(struct ldb_context *ldb, const char *url,
 178                               unsigned int flags, const char *options[],
 179                               struct ldb_module **module);
 180
 181 struct ldb_backend_ops {
 182         const char *name;
 183         ldb_connect_fn connect_fn;
 184 };
 185
 186 const char *ldb_default_modules_dir(void);
 187
 188 int ldb_register_backend(const char *url_prefix, ldb_connect_fn, bool);
 189
 190 struct ldb_handle *ldb_handle_new(TALLOC_CTX *mem_ctx, struct ldb_context *ldb);
 191
 192 int ldb_module_send_entry(struct ldb_request *req,
 193                           struct ldb_message *msg,
 194                           struct ldb_control **ctrls);
 195
 196 int ldb_module_send_referral(struct ldb_request *req,
 197                                            char *ref);
 198
 199 int ldb_module_done(struct ldb_request *req,
 200                     struct ldb_control **ctrls,
 201                     struct ldb_extended *response,
 202                     int error);
 203
 204 int ldb_mod_register_control(struct ldb_module *module, const char *oid);
 205
 206 void ldb_set_default_dns(struct ldb_context *ldb);
 207 /**
 208   Add a ldb_control to a ldb_reply
 209
 210   \param ares the reply struct where to add the control
 211   \param oid the object identifier of the control as string
 212   \param critical whether the control should be critical or not
 213   \param data a talloc pointer to the control specific data
 214
 215   \return result code (LDB_SUCCESS on success, or a failure code)
 216 */
 217 int ldb_reply_add_control(struct ldb_reply *ares, const char *oid, bool critical, void *data);
 218
 219 /**
 220   mark a request as untrusted. This tells the rootdse module to remove
 221   unregistered controls
 222  */
 223 void ldb_req_mark_untrusted(struct ldb_request *req);
 224
 225 /**
 226    return true is a request is untrusted
 227  */
 228 bool ldb_req_is_untrusted(struct ldb_request *req);
 229
 230 /* load all modules from the given directory */
 231 int ldb_modules_load(const char *modules_path, const char *version);
 232
 233 /* init functions prototype */
 234 typedef int (*ldb_module_init_fn)(const char *);
 235
 236 /*
 237   general ldb hook function
 238  */
 239 enum ldb_module_hook_type { LDB_MODULE_HOOK_CMDLINE_OPTIONS     = 1,
 240                             LDB_MODULE_HOOK_CMDLINE_PRECONNECT  = 2,
 241                             LDB_MODULE_HOOK_CMDLINE_POSTCONNECT = 3 };
 242
 243 typedef int (*ldb_hook_fn)(struct ldb_context *, enum ldb_module_hook_type );
 244
 245 /*
 246   register a ldb hook function
 247  */
 248 int ldb_register_hook(ldb_hook_fn hook_fn);
 249
 250 /*
 251   call ldb hooks of a given type
 252  */
 253 int ldb_modules_hook(struct ldb_context *ldb, enum ldb_module_hook_type t);
 254
 255 #define LDB_MODULE_CHECK_VERSION(version) do { \
 256  if (strcmp(version, LDB_VERSION) != 0) { \
 257         fprintf(stderr, "ldb: module version mismatch in %s : ldb_version=%s module_version=%s\n", \
 258                         __FILE__, version, LDB_VERSION); \
 259         return LDB_ERR_UNAVAILABLE; \
 260  }} while (0)
 261
 262
 263 /*
 264   return a string representation of the calling chain for the given
 265   ldb request
 266  */
 267 char *ldb_module_call_chain(struct ldb_request *req, TALLOC_CTX *mem_ctx);
 268
 269 /*
 270   return the next module in the chain
 271  */
 272 struct ldb_module *ldb_module_next(struct ldb_module *module);
 273
 274 /*
 275   set the next module in the module chain
 276  */
 277 void ldb_module_set_next(struct ldb_module *module, struct ldb_module *next);
 278
 279 /*
 280   load a list of modules
 281  */
 282 int ldb_module_load_list(struct ldb_context *ldb, const char **module_list,
 283                          struct ldb_module *backend, struct ldb_module **out);
 284
 285 /*
 286   get the popt_options pointer in the ldb structure. This allows a ldb
 287   module to change the command line parsing
 288  */
 289 struct poptOption **ldb_module_popt_options(struct ldb_context *ldb);
 290
 291 /* modules are called in inverse order on the stack.
 292    Lets place them as an admin would think the right order is.
 293    Modules order is important */
 294 const char **ldb_modules_list_from_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *string);
 295
 296 /*
 297   return the current ldb flags LDB_FLG_*
 298  */
 299 uint32_t ldb_module_flags(struct ldb_context *ldb);
 300
 301 int ldb_module_connect_backend(struct ldb_context *ldb,
 302                                const char *url,
 303                                const char *options[],
 304                                struct ldb_module **backend_module);
 305
 306 /*
 307   initialise a chain of modules
 308  */
 309 int ldb_module_init_chain(struct ldb_context *ldb, struct ldb_module *module);
 310
 311
 312 #endif