ldb database library
Copyright (C) Andrew Tridgell 2004
+ Copyright (C) Stefan Metzmacher 2004
** NOTE! The following LGPL license applies to the ldb
** library. This does NOT imply that all of Samba is released
* Description: defines for base ldb API
*
* Author: Andrew Tridgell
+ * Author: Stefan Metzmacher
*/
+#ifndef _LDB_H_
+#define _LDB_H_ 1
+
/*
major restrictions as compared to normal LDAP:
*/
-
/*
an individual lump of data in a result comes in this format. The
pointer will usually be to a UTF-8 string if the application is
sensible, but it can be to anything you like, including binary data
blobs of arbitrary size.
*/
+#ifndef ldb_val
struct ldb_val {
- unsigned int length;
- void *data;
+ uint8_t *data;
+ size_t length;
};
+#endif
/* these flags are used in ldd_message_element.flags fields. The
LDA_FLAGS_MOD_* flags are used in ldap_modify() calls to specify
#define LDB_FLAG_MOD_DELETE 3
+/*
+ well known object IDs
+*/
+#define LDB_OID_COMPARATOR_AND "1.2.840.113556.1.4.803"
+#define LDB_OID_COMPARATOR_OR "1.2.840.113556.1.4.804"
+
/*
results are given back as arrays of ldb_message_element
*/
struct ldb_message_element {
unsigned int flags;
- char *name;
+ const char *name;
unsigned int num_values;
struct ldb_val *values;
};
*/
struct ldb_ldif {
enum ldb_changetype changetype;
- struct ldb_message msg;
+ struct ldb_message *msg;
};
enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *);
-/*
- these function pointers define the operations that a ldb backend must perform
- they correspond exactly to the ldb_*() interface
-*/
-struct ldb_backend_ops {
- int (*close)(struct ldb_context *);
- int (*search)(struct ldb_context *, const char *, enum ldb_scope,
- const char *, const char *[], struct ldb_message ***);
- int (*search_free)(struct ldb_context *, struct ldb_message **);
- int (*add_record)(struct ldb_context *, const struct ldb_message *);
- int (*modify_record)(struct ldb_context *, const struct ldb_message *);
- int (*delete_record)(struct ldb_context *, const char *);
- const char * (*errstring)(struct ldb_context *);
+struct ldb_module;
+
+/* debugging uses one of the following levels */
+enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR,
+ LDB_DEBUG_WARNING, LDB_DEBUG_TRACE};
+
+/*
+ the user can optionally supply a debug function. The function
+ is based on the vfprintf() style of interface, but with the addition
+ of a severity level
+*/
+struct ldb_debug_ops {
+ void (*debug)(void *context, enum ldb_debug_level level,
+ const char *fmt, va_list ap);
+ void *context;
};
+#define LDB_FLG_RDONLY 1
+
+#ifndef PRINTF_ATTRIBUTE
+#define PRINTF_ATTRIBUTE(a,b)
+#endif
+
+
+/* structues for ldb_parse_tree handling code */
+enum ldb_parse_op { LDB_OP_AND=1, LDB_OP_OR=2, LDB_OP_NOT=3,
+ LDB_OP_EQUALITY=4, LDB_OP_SUBSTRING=5,
+ LDB_OP_GREATER=6, LDB_OP_LESS=7, LDB_OP_PRESENT=8,
+ LDB_OP_APPROX=9, LDB_OP_EXTENDED=10 };
+
+struct ldb_parse_tree {
+ enum ldb_parse_op operation;
+ union {
+ struct {
+ struct ldb_parse_tree *child;
+ } isnot;
+ struct {
+ char *attr;
+ struct ldb_val value;
+ } equality;
+ struct {
+ char *attr;
+ int start_with_wildcard;
+ int end_with_wildcard;
+ struct ldb_val **chunks;
+ } substring;
+ struct {
+ char *attr;
+ } present;
+ struct {
+ char *attr;
+ struct ldb_val value;
+ } comparison;
+ struct {
+ char *attr;
+ int dnAttributes;
+ char *rule_id;
+ struct ldb_val value;
+ } extended;
+ struct {
+ unsigned int num_elements;
+ struct ldb_parse_tree **elements;
+ } list;
+ } u;
+};
+
+struct ldb_parse_tree *ldb_parse_tree(void *mem_ctx, const char *s);
+char *ldb_filter_from_tree(void *mem_ctx, struct ldb_parse_tree *tree);
+char *ldb_binary_encode(void *ctx, struct ldb_val val);
+
+
/*
- every ldb connection is started by establishing a ldb_context
+ functions for controlling attribute handling
*/
-struct ldb_context {
- /* a private pointer for the backend to use */
- void *private_data;
+typedef int (*ldb_attr_handler_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, struct ldb_val *);
+typedef int (*ldb_attr_comparison_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, const struct ldb_val *);
+
+struct ldb_attrib_handler {
+ const char *attr;
+
+ /* LDB_ATTR_FLAG_* */
+ unsigned flags;
+
+ /* convert from ldif to binary format */
+ ldb_attr_handler_t ldif_read_fn;
- /* the operations provided by the backend */
- const struct ldb_backend_ops *ops;
+ /* convert from binary to ldif format */
+ ldb_attr_handler_t ldif_write_fn;
+
+ /* canonicalise a value, for use by indexing and dn construction */
+ ldb_attr_handler_t canonicalise_fn;
+
+ /* compare two values */
+ ldb_attr_comparison_t comparison_fn;
};
+#define LDB_ATTR_FLAG_HIDDEN (1<<0)
-#define LDB_FLG_RDONLY 1
+/* well-known ldap attribute syntaxes - see rfc2252 section 4.3.2 */
+#define LDB_SYNTAX_DN "1.3.6.1.4.1.1466.115.121.1.12"
+#define LDB_SYNTAX_DIRECTORY_STRING "1.3.6.1.4.1.1466.115.121.1.15"
+#define LDB_SYNTAX_INTEGER "1.3.6.1.4.1.1466.115.121.1.27"
+#define LDB_SYNTAX_OCTET_STRING "1.3.6.1.4.1.1466.115.121.1.40"
+#define LDB_SYNTAX_OBJECTCLASS "LDB_SYNTAX_OBJECTCLASS"
+
+/*
+ initialise a ldb context
+*/
+struct ldb_context *ldb_init(void *mem_ctx);
/*
connect to a database. The URL can either be one of the following forms
the options are passed uninterpreted to the backend, and are
backend specific
*/
-struct ldb_context *ldb_connect(const char *url, unsigned int flags,
- const char *options[]);
-
-/*
- close the connection to the database
-*/
-int ldb_close(struct ldb_context *ldb);
-
+int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
/*
search the database given a LDAP-like search expression
return the number of records found, or -1 on error
+
+ use talloc_free to free the ldb_message returned
*/
int ldb_search(struct ldb_context *ldb,
const char *base,
enum ldb_scope scope,
const char *expression,
- char * const attrs[], struct ldb_message ***res);
+ const char * const *attrs, struct ldb_message ***res);
-/*
- free a set of messages returned by ldb_search
+/*
+ like ldb_search() but takes a parse tree
*/
-int ldb_search_free(struct ldb_context *ldb, struct ldb_message **msgs);
-
+int ldb_search_bytree(struct ldb_context *ldb,
+ const char *base,
+ enum ldb_scope scope,
+ struct ldb_parse_tree *tree,
+ const char * const *attrs, struct ldb_message ***res);
/*
add a record to the database. Will fail if a record with the given class and key
int ldb_modify(struct ldb_context *ldb,
const struct ldb_message *message);
+/*
+ rename a record in the database
+*/
+int ldb_rename(struct ldb_context *ldb, const char *olddn, const char *newdn);
+
+/*
+ create a named lock
+*/
+int ldb_lock(struct ldb_context *ldb, const char *lockname);
+
+/*
+ release a named lock
+*/
+int ldb_unlock(struct ldb_context *ldb, const char *lockname);
+
/*
delete a record from the database
*/
*/
const char *ldb_errstring(struct ldb_context *ldb);
+/*
+ casefold a string (should be UTF8, but at the moment it isn't)
+*/
+char *ldb_casefold(void *mem_ctx, const char *s);
+int ldb_caseless_cmp(const char *s1, const char *s2);
+
/*
ldif manipulation functions
*/
-int ldif_write(int (*fprintf_fn)(void *, const char *, ...),
- void *private_data,
- const struct ldb_ldif *ldif);
-void ldif_read_free(struct ldb_ldif *);
-struct ldb_ldif *ldif_read(int (*fgetc_fn)(void *), void *private_data);
-struct ldb_ldif *ldif_read_file(FILE *f);
-struct ldb_ldif *ldif_read_string(const char *s);
-int ldif_write_file(FILE *f, const struct ldb_ldif *msg);
+int ldb_ldif_write(struct ldb_context *ldb,
+ int (*fprintf_fn)(void *, const char *, ...),
+ void *private_data,
+ const struct ldb_ldif *ldif);
+void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *);
+struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
+ int (*fgetc_fn)(void *), void *private_data);
+struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
+struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
+int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
+char *ldb_base64_encode(void *mem_ctx, const char *buf, int len);
+int ldb_base64_decode(char *s);
+int ldb_attrib_add_handlers(struct ldb_context *ldb,
+ const struct ldb_attrib_handler *handlers,
+ unsigned num_handlers);
+
+
+/* useful functions for ldb_message structure manipulation */
+
+int ldb_dn_cmp(struct ldb_context *ldb, const char *dn1, const char *dn2);
+int ldb_attr_cmp(const char *dn1, const char *dn2);
+
+/* case-fold a DN */
+char *ldb_dn_fold(void * mem_ctx,
+ const char * dn,
+ void * user_data,
+ int (* case_fold_attr_fn)(void * user_data, char * attr));
+
+/* create an empty message */
+struct ldb_message *ldb_msg_new(void *mem_ctx);
+
+/* find an element within an message */
+struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg,
+ const char *attr_name);
+
+/* compare two ldb_val values - return 0 on match */
+int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
+
+/* find a value within an ldb_message_element */
+struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el,
+ struct ldb_val *val);
+
+/* add a new empty element to a ldb_message */
+int ldb_msg_add_empty(struct ldb_context *ldb,
+ struct ldb_message *msg, const char *attr_name, int flags);
+
+/* add a element to a ldb_message */
+int ldb_msg_add(struct ldb_context *ldb,
+ struct ldb_message *msg,
+ const struct ldb_message_element *el,
+ int flags);
+int ldb_msg_add_value(struct ldb_context *ldb,
+ struct ldb_message *msg,
+ const char *attr_name,
+ const struct ldb_val *val);
+int ldb_msg_add_string(struct ldb_context *ldb, struct ldb_message *msg,
+ const char *attr_name, const char *str);
+int ldb_msg_add_fmt(struct ldb_context *ldb, struct ldb_message *msg,
+ const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(4,5);
+
+/* compare two message elements - return 0 on match */
+int ldb_msg_element_compare(struct ldb_message_element *el1,
+ struct ldb_message_element *el2);
+
+/* find elements in a message and convert to a specific type, with
+ a give default value if not found. Assumes that elements are
+ single valued */
+const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
+int ldb_msg_find_int(const struct ldb_message *msg,
+ const char *attr_name,
+ int default_value);
+unsigned int ldb_msg_find_uint(const struct ldb_message *msg,
+ const char *attr_name,
+ unsigned int default_value);
+int64_t ldb_msg_find_int64(const struct ldb_message *msg,
+ const char *attr_name,
+ int64_t default_value);
+uint64_t ldb_msg_find_uint64(const struct ldb_message *msg,
+ const char *attr_name,
+ uint64_t default_value);
+double ldb_msg_find_double(const struct ldb_message *msg,
+ const char *attr_name,
+ double default_value);
+const char *ldb_msg_find_string(const struct ldb_message *msg,
+ const char *attr_name,
+ const char *default_value);
+
+void ldb_msg_sort_elements(struct ldb_message *msg);
+
+void ldb_msg_free(struct ldb_context *ldb, struct ldb_message *msg);
+
+struct ldb_message *ldb_msg_copy(struct ldb_context *ldb,
+ const struct ldb_message *msg);
+
+struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb,
+ const struct ldb_message *msg);
+
+
+struct ldb_message *ldb_msg_diff(struct ldb_context *ldb,
+ struct ldb_message *msg1,
+ struct ldb_message *msg2);
+
+struct ldb_val ldb_val_dup(void *mem_ctx, const struct ldb_val *v);
+
+/*
+ this allows the user to set a debug function for error reporting
+*/
+int ldb_set_debug(struct ldb_context *ldb,
+ void (*debug)(void *context, enum ldb_debug_level level,
+ const char *fmt, va_list ap),
+ void *context);
+
+/* this sets up debug to print messages on stderr */
+int ldb_set_debug_stderr(struct ldb_context *ldb);
+
+/* control backend specific opaque values */
+int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
+void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
+
+#endif
git.samba.org / jelmer / samba4-debian.git / blobdiff