sin/samba-mirror
1
0
Fork 0
mirror of https://github.com/samba-team/samba.git synced 2025-08-02 00:22:11 +03:00
Code Activity

r12850: - add Doxygen comments to ldb

Browse Source 
- 'make doxygen' generated the api documentation under apidocs/

Many thanks to Brad Hards <bradh@frogmouth.net> for the patches!

metze
(This used to be commit e98d483174)
This commit is contained in:
Stefan Metzmacher
2006-01-11 16:31:57 +00:00
committed by Gerald (Jerry) Carter
parent c07d16d201
commit 4a8656fd65
7 changed files with 2091 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1229
source4/lib/ldb/Doxyfile Normal file
View File

File diff suppressed because it is too large Load Diff

7
source4/lib/ldb/Makefile.in
View File

@ -1,6 +1,7 @@
CC = @CC@
GCOV = @GCOV@
XSLTPROC = @XSLTPROC@
DOXYGEN = @DOXYGEN@
prefix = @prefix@
exec_prefix = @exec_prefix@
includedir = @includedir@
@ -76,7 +77,7 @@ MANPAGES = $(patsubst %.xml,%,$(wildcard man/*.xml))
EXAMPLES = examples/ldbreader examples/ldifreader
all: $(DIRS) $(BINS) $(LIBS) $(EXAMPLES) $(MANPAGES)
all: $(DIRS) $(BINS) $(LIBS) $(EXAMPLES) $(MANPAGES) doxygen
.c.o:
@echo Compiling $*.c
@ -131,11 +132,15 @@ examples/ldifreader: examples/ldifreader.o $(LIBS)
%.html: %.xml
test -z "$(XSLTPROC)" || $(XSLTPROC) -o $@ http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $<
doxygen:
test -z "$(DOXYGEN)" || $(DOXYGEN)
clean:
rm -f */*.o *.gcov */*.gc?? tdbtest.ldb* \
rm -f $(BINS) $(TDB_OBJ) $(TALLOC_OBJ) $(LDB_LIB)
rm -f $(MANPAGES)
rm -f $(EXAMPLES)
rm -rf apidocs/
distclean: clean
rm -f *~ */*~

1
source4/lib/ldb/configure.in
View File

@ -21,6 +21,7 @@ AC_SUBST(WITH_GCOV)
AC_PROG_CC
AC_FUNC_MMAP
AC_PATH_PROG(XSLTPROC,xsltproc)
AC_PATH_PROG(DOXYGEN,doxygen)
AC_PATH_PROG(GCOV,gcov)
AC_CHECK_HEADERS(stdint.h)
AC_CONFIG_HEADER(include/config.h)

16
source4/lib/ldb/examples.dox Normal file
View File

@ -0,0 +1,16 @@
/** \example ldbreader.c
The code below shows a simple LDB application.
It lists / dumps the records in a LDB database to standard output.
*/
/** \example ldifreader.c
The code below shows a simple LDB application.
It lists / dumps the entries in an LDIF file to standard output.
*/

600
source4/lib/ldb/include/ldb.h
View File

@ -35,8 +35,17 @@
* Author: Stefan Metzmacher
*/
/**
\file ldb.h Samba's ldb database
This header file provides the main API for ldb.
*/
#ifndef _LDB_H_
/*! \cond DOXYGEN_IGNORE */
#define _LDB_H_ 1
/*! \endcond */
/*
major restrictions as compared to normal LDAP:
@ -53,45 +62,85 @@
*/
/*
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
/**
Result value
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.
\note the data is null (0x00) terminated, but the length does not
include the terminator.
*/
struct ldb_val {
uint8_t *data;
size_t length;
uint8_t *data; /*!< result data */
size_t length; /*!< length of data */
};
#endif
/* internal ldb exploded dn structures */
/**
internal ldb exploded dn structures
*/
struct ldb_dn_component {
char *name;
char *name;
struct ldb_val value;
};
struct ldb_dn {
int comp_num;
struct ldb_dn_component *components;
};
/* these flags are used in ldb_message_element.flags fields. The
LDA_FLAGS_MOD_* flags are used in ldap_modify() calls to specify
whether attributes are being added, deleted or modified */
/**
There are a number of flags that are used with ldap_modify() in
ldb_message_element.flags fields. The LDA_FLAGS_MOD_ADD,
LDA_FLAGS_MOD_DELETE and LDA_FLAGS_MOD_REPLACE flags are used in
ldap_modify() calls to specify whether attributes are being added,
deleted or modified respectively.
*/
#define LDB_FLAG_MOD_MASK 0x3
/**
Flag value used in ldap_modify() to indicate that attributes are
being added.
\sa LDB_FLAG_MOD_MASK
*/
#define LDB_FLAG_MOD_ADD 1
/**
Flag value used in ldap_modify() to indicate that attributes are
being replaced.
\sa LDB_FLAG_MOD_MASK
*/
#define LDB_FLAG_MOD_REPLACE 2
/**
Flag value used in ldap_modify() to indicate that attributes are
being deleted.
\sa LDB_FLAG_MOD_MASK
*/
#define LDB_FLAG_MOD_DELETE 3
/**
OID for logic AND comaprison.
/*
well known object IDs
This is the well known object ID for a logical AND comparitor.
*/
#define LDB_OID_COMPARATOR_AND "1.2.840.113556.1.4.803"
/**
OID for logic OR comparison.
This is the well known object ID for a logical OR comparitor.
*/
#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 {
@ -102,7 +151,7 @@ struct ldb_message_element {
};
/*
/**
a ldb_message represents all or part of a record. It can contain an arbitrary
number of elements.
*/
@ -120,12 +169,15 @@ enum ldb_changetype {
LDB_CHANGETYPE_MODIFY
};
/*
a ldif record - from ldif_read
/**
LDIF record
This structure contains a LDIF record, as returned from ldif_read()
and equivalent functions.
*/
struct ldb_ldif {
enum ldb_changetype changetype;
struct ldb_message *msg;
enum ldb_changetype changetype; /*!< The type of change */
struct ldb_message *msg; /*!< The changes */
};
enum ldb_scope {LDB_SCOPE_DEFAULT=-1,
@ -145,7 +197,7 @@ typedef int (*ldb_traverse_fn)(struct ldb_context *, const struct ldb_message *)
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
@ -156,14 +208,31 @@ struct ldb_debug_ops {
void *context;
};
/**
Flag value for database connection mode.
If LDB_FLG_RDONLY is used in ldb_connect, then the database will be
opened read-only, if possible.
*/
#define LDB_FLG_RDONLY 1
/**
Flag value for database connection mode.
If LDB_FLG_NOSYNC is used in ldb_connect, then the database will be
opened without synchronous operations, if possible.
*/
#define LDB_FLG_NOSYNC 2
/*! \cond DOXYGEN_IGNORE */
#ifndef PRINTF_ATTRIBUTE
#define PRINTF_ATTRIBUTE(a,b)
#endif
/*! \endcond */
/* structures for ldb_parse_tree handling code */
/*
structures 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,
@ -235,24 +304,106 @@ struct ldb_attrib_handler {
ldb_attr_comparison_t comparison_fn;
};
#define LDB_ATTR_FLAG_HIDDEN (1<<0) /* the attribute is not returned by default */
#define LDB_ATTR_FLAG_CONSTRUCTED (1<<1) /* the attribute is constructed from other attributes */
/**
The attribute is not returned by default
*/
#define LDB_ATTR_FLAG_HIDDEN (1<<0)
/**
The attribute is constructed from other attributes
*/
#define LDB_ATTR_FLAG_CONSTRUCTED (1<<1)
/* well-known ldap attribute syntaxes - see rfc2252 section 4.3.2 */
/**
LDAP attribute syntax for a DN
This is the well-known LDAP attribute syntax for a DN.
See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
*/
#define LDB_SYNTAX_DN "1.3.6.1.4.1.1466.115.121.1.12"
/**
LDAP attribute syntax for a Directory String
This is the well-known LDAP attribute syntax for a Directory String.
See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
*/
#define LDB_SYNTAX_DIRECTORY_STRING "1.3.6.1.4.1.1466.115.121.1.15"
/**
LDAP attribute syntax for an integer
This is the well-known LDAP attribute syntax for an integer.
See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
*/
#define LDB_SYNTAX_INTEGER "1.3.6.1.4.1.1466.115.121.1.27"
/**
LDAP attribute syntax for an octet string
This is the well-known LDAP attribute syntax for an octet string.
See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
*/
#define LDB_SYNTAX_OCTET_STRING "1.3.6.1.4.1.1466.115.121.1.40"
/**
LDAP attribute syntax for UTC time.
This is the well-known LDAP attribute syntax for a UTC time.
See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2
*/
#define LDB_SYNTAX_UTC_TIME "1.3.6.1.4.1.1466.115.121.1.53"
#define LDB_SYNTAX_OBJECTCLASS "LDB_SYNTAX_OBJECTCLASS"
/* sorting helpers */
typedef int (*ldb_qsort_cmp_fn_t) (const void *, const void *, const void *);
/**
OID for the paged results control. This control is included in the
searchRequest and searchResultDone messages as part of the controls
field of the LDAPMessage, as defined in Section 4.1.12 of
LDAP v3.
\sa <a href="http://www.ietf.org/rfc/rfc2696.txt">RFC 2696</a>.
*/
#define LDB_CONTROL_PAGED_RESULTS_OID "1.2.840.113556.1.4.319"
/**
OID for extended DN
\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>
*/
#define LDB_CONTROL_EXTENDED_DN_OID "1.2.840.113556.1.4.529"
/**
OID for LDAP server sort result extension.
This control is included in the searchRequest message as part of
the controls field of the LDAPMessage, as defined in Section 4.1.12
of LDAP v3. The controlType is set to
"1.2.840.113556.1.4.473". The criticality MAY be either TRUE or
FALSE (where absent is also equivalent to FALSE) at the client's
option.
\sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
*/
#define LDB_CONTROL_SERVER_SORT_OID "1.2.840.113556.1.4.473"
/**
OID for LDAP server sort result response extension.
This control is included in the searchResultDone message as part of
the controls field of the LDAPMessage, as defined in Section 4.1.12 of
LDAP v3.
\sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
*/
#define LDB_CONTROL_SORT_RESP_OID "1.2.840.113556.1.4.474"
struct ldb_paged_control {
@ -347,29 +498,60 @@ struct ldb_request {
int ldb_request(struct ldb_context *ldb, struct ldb_request *request);
/*
initialise a ldb context
/**
Initialise an ldb context
This is required before any other LDB call.
\param mem_ctx pointer to a talloc memory context. Pass NULL if there is
no suitable context available.
\return pointer to ldb_context that should be free'd (using talloc_free())
at the end of the program.
*/
struct ldb_context *ldb_init(void *mem_ctx);
/*
connect to a database. The URL can either be one of the following forms
ldb://path
ldapi://path
/**
Connect to a database.
flags is made up of LDB_FLG_*
This is typically called soon after ldb_init(), and is required prior to
any search or database modification operations.
the options are passed uninterpreted to the backend, and are
backend specific
The URL can be one of the following forms:
- tdb://path
- ldapi://path
- ldap://host
- sqlite3://path
\param ldb the context associated with the database (from ldb_init())
\param url the URL of the database to connect to, as noted above
\param flags a combination of LDB_FLG_* to modify the connection behaviour
\param options backend specific options - passed uninterpreted to the backend
\return result code (LDB_SUCCESS on success, or a failure code)
\note It is an error to connect to a database that does not exist in readonly mode
(that is, with LDB_FLG_RDONLY). However in read-write mode, the database will be
created if it does not exist.
*/
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
/**
Search the database
return the number of records found, or -1 on error
This function searches the database, and returns
records that match an LDAP-like search expression
use talloc_free to free the ldb_message returned
\param ldb the context associated with the database (from ldb_init())
\param base the Base Distinguished Name for the query (pass NULL for root DN)
\param scope the search scope for the query
\param expression the search expression to use for this query
\param attrs the search attributes for the query (pass NULL if none required)
\param res the return result
\return result code (LDB_SUCCESS on success, or a failure code)
\note use talloc_free() to free the ldb_result returned
*/
int ldb_search(struct ldb_context *ldb,
const struct ldb_dn *base,
@ -386,71 +568,263 @@ int ldb_search_bytree(struct ldb_context *ldb,
struct ldb_parse_tree *tree,
const char * const *attrs, struct ldb_result **res);
/*
add a record to the database. Will fail if a record with the given class and key
already exists
/**
Add a record to the database.
This function adds a record to the database. This function will fail
if a record with the specified class and key already exists in the
database.
\param ldb the context associated with the database (from
ldb_init())
\param message the message containing the record to add.
\return result code (LDB_SUCCESS if the record was added, otherwise
a failure code)
*/
int ldb_add(struct ldb_context *ldb,
const struct ldb_message *message);
/*
modify the specified attributes of a record
/**
Modify the specified attributes of a record
This function modifies a record that is in the database.
\param ldb the context associated with the database (from
ldb_init())
\param message the message containing the changes required.
\return result code (LDB_SUCCESS if the record was modified as
requested, otherwise a failure code)
*/
int ldb_modify(struct ldb_context *ldb,
const struct ldb_message *message);
/*
rename a record in the database
/**
Rename a record in the database
This function renames a record in the database.
\param ldb the context associated with the database (from
ldb_init())
\param olddn the DN for the record to be renamed.
\param newdn the new DN
\return result code (LDB_SUCCESS if the record was renamed as
requested, otherwise a failure code)
*/
int ldb_rename(struct ldb_context *ldb, const struct ldb_dn *olddn, const struct ldb_dn *newdn);
/*
delete a record from the database
/**
Delete a record from the database
This function deletes a record from the database.
\param ldb the context associated with the database (from
ldb_init())
\param dn the DN for the record to be deleted.
\return result code (LDB_SUCCESS if the record was deleted,
otherwise a failure code)
*/
int ldb_delete(struct ldb_context *ldb, const struct ldb_dn *dn);
/*
/**
start a transaction
*/
int ldb_transaction_start(struct ldb_context *ldb);
/*
/**
commit a transaction
*/
int ldb_transaction_commit(struct ldb_context *ldb);
/*
/**
cancel a transaction
*/
int ldb_transaction_cancel(struct ldb_context *ldb);
/*
/**
return extended error information from the last call
*/
const char *ldb_errstring(struct ldb_context *ldb);
/*
casefold a string (should be UTF8, but at the moment it isn't)
/**
Casefold a string
\param mem_ctx the memory context to allocate the result string
memory from.
\param s the string that is to be folded
\return a copy of the string, converted to upper case
\todo This function should be UTF8 aware, but currently is not.
*/
char *ldb_casefold(void *mem_ctx, const char *s);
/**
Compare two strings, without regard to case.
\param s1 the first string to compare
\param s2 the second string to compare
\return 0 if the strings are the same, non-zero if there are any
differences except for case.
\note This function is not UTF8 aware.
*/
int ldb_caseless_cmp(const char *s1, const char *s2);
/*
ldif manipulation functions
*/
/**
Write an LDIF message
This function writes an LDIF message using a caller supplied write
function.
\param ldb the ldb context (from ldb_init())
\param fprintf_fn a function pointer for the write function. This must take
a private data pointer, followed by a format string, and then a variable argument
list.
\param private_data pointer that will be provided back to the write
function. This is useful for maintaining state or context.
\param ldif the message to write out
\return the total number of bytes written, or an error code as returned
from the write function.
\sa ldb_ldif_write_file for a more convenient way to write to a
file stream.
\sa ldb_ldif_read for the reader equivalent to this function.
*/
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 *);
/**
Clean up an LDIF message
This function cleans up a LDIF message read using ldb_ldif_read()
or related functions (such as ldb_ldif_read_string() and
ldb_ldif_read_file().
\param ldb the ldb context (from ldb_init())
\param msg the message to clean up and free
*/
void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *msg);
/**
Read an LDIF message
This function creates an LDIF message using a caller supplied read
function.
\param ldb the ldb context (from ldb_init())
\param fgetc_fn a function pointer for the read function. This must
take a private data pointer, and must return a pointer to an
integer corresponding to the next byte read (or EOF if there is no
more data to be read).
\param private_data pointer that will be provided back to the read
function. This is udeful for maintaining state or context.
\return the LDIF message that has been read in
\note You must free the LDIF message when no longer required, using
ldb_ldif_read_free().
\sa ldb_ldif_read_file for a more convenient way to read from a
file stream.
\sa ldb_ldif_read_string for a more convenient way to read from a
string (char array).
\sa ldb_ldif_write for the writer equivalent to this function.
*/
struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb,
int (*fgetc_fn)(void *), void *private_data);
/**
Read an LDIF message from a file
This function reads the next LDIF message from the contents of a
file stream. If you want to get all of the LDIF messages, you will
need to repeatedly call this function, until it returns NULL.
\param ldb the ldb context (from ldb_init())
\param f the file stream to read from (typically from fdopen())
\sa ldb_ldif_read_string for an equivalent function that will read
from a string (char array).
\sa ldb_ldif_write_file for the writer equivalent to this function.
*/
struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f);
/**
Read an LDIF message from a string
This function reads the next LDIF message from the contents of a char
array. If you want to get all of the LDIF messages, you will need
to repeatedly call this function, until it returns NULL.
\param ldb the ldb context (from ldb_init())
\param s pointer to the char array to read from
\sa ldb_ldif_read_file for an equivalent function that will read
from a file stream.
\sa ldb_ldif_write for a more general (arbitrary read function)
version of this function.
*/
struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s);
/**
Write an LDIF message to a file
\param ldb the ldb context (from ldb_init())
\param f the file stream to write to (typically from fdopen())
\param msg the message to write out
\return the total number of bytes written, or a negative error code
\sa ldb_ldif_read_file for the reader equivalent to this function.
*/
int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg);
/**
Base64 encode a buffer
\param mem_ctx the memory context that the result is allocated
from.
\param buf pointer to the array that is to be encoded
\param len the number of elements in the array to be encoded
\return pointer to an array containing the encoded data
\note The caller is responsible for freeing the result
*/
char *ldb_base64_encode(void *mem_ctx, const char *buf, int len);
/**
Base64 decode a buffer
This function decodes a base64 encoded string in place.
\param s the string to decode.
\return the length of the returned (decoded) string.
\note the string is null terminated, but the null terminator is not
included in the length.
*/
int ldb_base64_decode(char *s);
int ldb_attrib_add_handlers(struct ldb_context *ldb,
const struct ldb_attrib_handler *handlers,
unsigned num_handlers);
@ -486,28 +860,67 @@ struct ldb_dn_component *ldb_dn_get_rdn(void *mem_ctx, const struct ldb_dn *dn);
/* useful functions for ldb_message structure manipulation */
int ldb_dn_cmp(struct ldb_context *ldb, const char *dn1, const char *dn2);
/**
Compare two attributes
This function compares to attribute names. Note that this is a
case-insensitive comparison.
\param attr1 the first attribute name to compare
\param attr2 the second attribute name to compare
\return 0 if the attribute names are the same, or only differ in
case; non-zero if there are any differences
*/
int ldb_attr_cmp(const char *attr1, const char *attr2);
int ldb_attr_dn(const char *attr);
char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
/* create an empty message */
/**
Create an empty message
\param mem_ctx the memory context to create in. You can pass NULL
to get the top level context, however the ldb context (from
ldb_init()) may be a better choice
*/
struct ldb_message *ldb_msg_new(void *mem_ctx);
/* find an element within an message */
/**
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 */
/**
Compare two ldb_val values
\param v1 first ldb_val structure to be tested
\param v2 second ldb_val structure to be tested
\return 1 for a match, 0 if there is any difference
*/
int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2);
/* find a value within an ldb_message_element */
/**
find a value within an ldb_message_element
\param el the element to search
\param val the value to search for
\note This search is case sensitive
*/
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 */
/**
add a new empty element to a ldb_message
*/
int ldb_msg_add_empty(struct ldb_message *msg, const char *attr_name, int flags);
/* add a element to a ldb_message */
/**
add a element to a ldb_message
*/
int ldb_msg_add(struct ldb_message *msg,
const struct ldb_message_element *el,
int flags);
@ -519,13 +932,19 @@ int ldb_msg_add_string(struct ldb_message *msg,
int ldb_msg_add_fmt(struct ldb_message *msg,
const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
/* compare two message elements - return 0 on match */
/**
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
/**
Find elements in a message.
This function finds elements and converts to a specific type, with
a give default value if not found. Assumes that elements are
single valued */
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,
@ -561,11 +980,35 @@ struct ldb_message *ldb_msg_diff(struct ldb_context *ldb,
struct ldb_message *msg1,
struct ldb_message *msg2);
/**
Integrity check an ldb_message
This function performs basic sanity / integrity checks on an
ldb_message.
\param msg the message to check
\return LDB_SUCCESS if the message is OK, or a non-zero error code
(one of LDB_ERR_INVALID_DN_SYNTAX, LDB_ERR_ENTRY_ALREADY_EXISTS or
LDB_ERR_INVALID_ATTRIBUTE_SYNTAX) if there is a problem with a
message.
*/
int ldb_msg_sanity_check(const struct ldb_message *msg);
/**
Duplicate an ldb_val structure
This function copies an ldb value structure.
\param mem_ctx the memory context that the duplicated value will be
allocated from
\param v the ldb_val to be duplicated.
\return the duplicated ldb_val structure.
*/
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,
@ -573,7 +1016,9 @@ int ldb_set_debug(struct ldb_context *ldb,
const char *fmt, va_list ap),
void *context);
/* this sets up debug to print messages on stderr */
/**
this sets up debug to print messages on stderr
*/
int ldb_set_debug_stderr(struct ldb_context *ldb);
/* control backend specific opaque values */
@ -596,7 +1041,30 @@ int ldb_msg_rename_attr(struct ldb_message *msg, const char *attr, const char *r
int ldb_msg_copy_attr(struct ldb_message *msg, const char *attr, const char *replace);
void ldb_msg_remove_attr(struct ldb_message *msg, const char *attr);
/**
Convert a time structure to a string
This function converts a time_t structure to an LDAP formatted time
string.
\param mem_ctx the memory context to allocate the return string in
\param t the time structure to convert
\return the formatted string, or NULL if the time structure could
not be converted
*/
char *ldb_timestring(void *mem_ctx, time_t t);
/**
Convert a string to a time structure
This function converts an LDAP formatted time string to a time_t
structure.
\param s the string to convert
\return the time structure, or 0 if the string cannot be converted
*/
time_t ldb_string_to_time(const char *s);
char *ldb_dn_canonical_string(void *mem_ctx, const struct ldb_dn *dn);

230
source4/lib/ldb/include/ldb_errors.h
View File

@ -33,59 +33,279 @@
*/
#ifndef _LDB_ERRORS_H_
#define _LDB_ERRORS_H_ 1
/*
* Not all error codes make sense for ldb,
* but they are keept here for reference anyway
/*! \cond DOXYGEN_IGNORE */
#define _LDB_ERRORS_H_ 1
/*! \endcond */
/**
\file ldb_errors.h
This header provides a set of result codes for LDB function calls.
Many LDB function calls return an integer value (int). As shown in
the function documentation, those return values may indicate
whether the function call worked correctly (in which case it
returns LDB_SUCCESS) or some problem occurred (in which case some
other value will be returned). As a special case,
LDB_ERR_COMPARE_FALSE or LDB_ERR_COMPARE_TRUE may be returned,
which does not indicate an error.
\note Not all error codes make sense for LDB, however they are
based on the LDAP error codes, and are kept for reference and to
avoid overlap.
\note Some of this documentation is based on information in
the OpenLDAP documentation, as developed and maintained by the
<a href="http://www.openldap.org/">The OpenLDAP Project</a>.
*/
/**
The function call succeeded.
If a function returns LDB_SUCCESS, then that function, and the
underlying transactions that may have been required, completed
successfully.
*/
#define LDB_SUCCESS 0
/**
The function call failed for some non-specific reason.
*/
#define LDB_ERR_OPERATIONS_ERROR 1
/**
The function call failed because of a protocol violation.
*/
#define LDB_ERR_PROTOCOL_ERROR 2
/**
The function call failed because a time limit was exceeded.
*/
#define LDB_ERR_TIME_LIMIT_EXCEEDED 3
/**
The function call failed because a size limit was exceeded.
*/
#define LDB_ERR_SIZE_LIMIT_EXCEEDED 4
/**
The function was for value comparison, and the comparison operation
returned false.
\note This is a status value, and doesn't normally indicate an
error.
*/
#define LDB_ERR_COMPARE_FALSE 5
/**
The function was for value comparison, and the comparison operation
returned true.
\note This is a status value, and doesn't normally indicate an
error.
*/
#define LDB_ERR_COMPARE_TRUE 6
/**
The function used an authentication method that is not supported by
the database.
*/
#define LDB_ERR_AUTH_METHOD_NOT_SUPPORTED 7
/**
The function call required a underlying operation that required
strong authentication.
This will normally only occur if you are using LDB with a LDAP
backend.
*/
#define LDB_ERR_STRONG_AUTH_REQUIRED 8
/* 9 RESERVED */
/**
The function resulted in a referral to another server.
*/
#define LDB_ERR_REFERRAL 10
/**
The function failed because an administrative / policy limit was
exceeded.
*/
#define LDB_ERR_ADMIN_LIMIT_EXCEEDED 11
/**
The function required an extension or capability that the
database cannot provide.
*/
#define LDB_ERR_UNSUPPORTED_CRITICAL_EXTENSION 12
/**
The function involved a transaction or database operation that
could not be performed without a secure link.
*/
#define LDB_ERR_CONFIDENTIALITY_REQUIRED 13
/**
This is an intermediate result code for SASL bind operations that
have more than one step.
\note This is a result code that does not normally indicate an
error has occurred.
*/
#define LDB_ERR_SASL_BIND_IN_PROGRESS 14
/**
The function referred to an attribute type that is not present in
the entry.
*/
#define LDB_ERR_NO_SUCH_ATTRIBUTE 16
/**
The function referred to an attribute type that is invalid
*/
#define LDB_ERR_UNDEFINED_ATTRIBUTE_TYPE 17
/**
The function required a filter type that is not available for the
specified attribute.
*/
#define LDB_ERR_INAPPROPRIATE_MATCHING 18
#define LDB_ERR_CONSTRAINT_VIOLAION 19
/**
The function would have violated an attribute constraint.
*/
#define LDB_ERR_CONSTRAINT_VIOLATION 19
/**
The function involved an attribute type or attribute value that
already exists in the entry.
*/
#define LDB_ERR_ATTRIBUTE_OR_VALUE_EXISTS 20
/**
The function used an invalid (incorrect syntax) attribute value.
*/
#define LDB_ERR_INVALID_ATTRIBUTE_SYNTAX 21
/* 22-31 unused */
/**
The function referred to an object that does not exist in the
database.
*/
#define LDB_ERR_NO_SUCH_OBJECT 32
/**
The function referred to an alias which points to a non-existant
object in the database.
*/
#define LDB_ERR_ALIAS_PROBLEM 33
/**
The function used a DN which was invalid (incorrect syntax).
*/
#define LDB_ERR_INVALID_DN_SYNTAX 34
/* 53 RESERVED */
/**
The function required dereferencing of an alias, and something went
wrong during the dereferencing process.
*/
#define LDB_ERR_ALIAS_DEREFERENCING_PROBLEM 36
/* 37-47 unused */
/**
The function passed in the wrong authentication method.
*/
#define LDB_ERR_INAPPROPRIATE_AUTHENTICATION 48
/**
The function passed in or referenced incorrect credentials during
authentication.
*/
#define LDB_ERR_INVALID_CREDENTIALS 49
/**
The function required access permissions that the user does not
possess.
*/
#define LDB_ERR_INSUFFICIENT_ACCESS_RIGHTS 50
/**
The function required a transaction or call that the database could
not perform because it is busy.
*/
#define LDB_ERR_BUSY 51
/**
The function required a transaction or call to a database that is
not available.
*/
#define LDB_ERR_UNAVAILABLE 52
/**
The function required a transaction or call to a database that the
database declined to perform.
*/
#define LDB_ERR_UNWILLING_TO_PERFORM 53
/**
The function failed because it resulted in a loop being detected.
*/
#define LDB_ERR_LOOP_DETECT 54
/* 55-63 unused */
/**
The function failed because it would have violated a naming rule.
*/
#define LDB_ERR_NAMING_VIOLATION 64
/**
The function failed because it would have violated the schema.
*/
#define LDB_ERR_OBJECT_CLASS_VIOLATION 65
/**
The function required an operation that is only allowed on leaf
objects, but the object is not a leaf.
*/
#define LDB_ERR_NOT_ALLOWED_ON_NON_LEAF 66
/**
The function required an operation that cannot be performed on a
Relative DN, but the object is a Relative DN.
*/
#define LDB_ERR_NOT_ALLOWED_ON_RDN 67
/**
The function failed because the entry already exists.
*/
#define LDB_ERR_ENTRY_ALREADY_EXISTS 68
/**
The function failed because modifications to an object class are
not allowable.
*/
#define LDB_ERR_OBJECT_CLASS_MODS_PROHIBITED 69
/* 70 RESERVED FOR CLDAP */
/**
The function failed because it needed to be applied to multiple
databases.
*/
#define LDB_ERR_AFFECTS_MULTIPLE_DSAS 71
/* 72-79 unused */
/**
The function failed for unknown reasons.
*/
#define LDB_ERR_OTHER 80
/* 81-90 RESERVED for APIs */
#endif /* _LDB_ERRORS_H_ */

80
source4/lib/ldb/mainpage.dox Normal file
View File

@ -0,0 +1,80 @@
/**
\mainpage ldb
\section Overview
ldb is a LDAP-like embedded database. It is not at all LDAP standards
compliant, so if you want a standards compliant database then please
see the excellent <a href="http://www.openldap.org/">OpenLDAP</a>
project.<p>
What ldb does is provide a fast database with an LDAP-like API
designed to be used within an application. In some ways it can be seen
as a intermediate solution between key-value pair databases and a real
LDAP database.<p>
ldb is the database engine used in Samba4.
\section Features
The main features that separate ldb from other solutions are:
- Safe multi-reader, multi-writer, using byte range locking
- LDAP-like API
- fast operation
- choice of local tdb, local sqlite3 or remote LDAP backends
- integration with <a href="http://talloc.samba.org">talloc</a>
- schema-less operation, for trivial setup
- modules for extensions (such as schema support)
- easy setup of indexes and attribute properties
- ldbedit tool for database editing (reminiscent of 'vipw')
- ldif for import/export
\section Documentation
ldb has limited programmer and administrator documentation:
- a list of <a href="globals_func.html">functions</a>
- a list of <a href="examples.html">examples</a>
- a list of <a href="annotated.html">data structures</a>
- a list of <a href="globals_defs.html">constants</a>
If you need more information than is presented in this document, you
may wish to look at the source code, especially the source code in the
<a href="http://samba.org/ftp/unpacked/samba4/source/lib/ldb/tools/">tools directory</a>.
ldb makes use of the LDAP Data Interchange Format (LDIF), which is
documented in <a href="http://www.ietf.org/rfc/rfc2849.txt">RFC
2849</a>.
\section Support
ldb does not currently have its own mailing list or bug tracking
system. For now, please use the <a
href="https://lists.samba.org/mailman/listinfo/samba-technical">samba-technical</a>
mailing list, and the <a href="http://bugzilla.samba.org/">Samba
bugzilla</a> bug tracking system.
\section Download
You can download the latest release either via rsync or anonymous
svn. To fetch via svn use the following commands:
\verbatim
svn co svn://svnanon.samba.org/samba/branches/SAMBA_4_0/source/lib/ldb ldb
svn co svn://svnanon.samba.org/samba/branches/SAMBA_4_0/source/lib/tdb tdb
svn co svn://svnanon.samba.org/samba/branches/SAMBA_4_0/source/lib/talloc talloc
\endverbatim
To fetch via rsync use these commands:
\verbatim
rsync -Pavz samba.org::ftp/unpacked/samba4/source/lib/ldb .
rsync -Pavz samba.org::ftp/unpacked/samba4/source/lib/tdb .
rsync -Pavz samba.org::ftp/unpacked/samba4/source/lib/talloc .
\endverbatim
\section Credits
ldb is another product of the prolific <a href="http://samba.org/~tridge/">Andrew Tridgell</a>.
*/