ldb.h

samba最新软件

/* 
   ldb database library

   Copyright (C) Andrew Tridgell  2004
   Copyright (C) Stefan Metzmacher  2004
   Copyright (C) Simo Sorce  2005-2006

     ** NOTE! The following LGPL license applies to the ldb
     ** library. This does NOT imply that all of Samba is released
     ** under the LGPL
   
   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 3 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public
   License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/

/*
 *  Name: ldb
 *
 *  Component: ldb header
 *
 *  Description: defines for base ldb API
 *
 *  Author: Andrew Tridgell
 *  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:

     - no async calls.
     - each record must have a unique key field
     - the key must be representable as a NULL terminated C string and may not 
       contain a comma or braces

  major restrictions as compared to tdb:

     - no explicit locking calls
     UPDATE: we have transactions now, better than locking --SSS.

*/

#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; /*!< result data */
	size_t length; /*!< length of data */
};
#endif

/*! \cond DOXYGEN_IGNORE */
#ifndef PRINTF_ATTRIBUTE
#define PRINTF_ATTRIBUTE(a,b)
#endif
/*! \endcond */

/* opaque ldb_dn structures, see ldb_dn.c for internals */
struct ldb_dn_component;
struct ldb_dn;

/**
 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.

  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 {
	unsigned int flags;
	const char *name;
	unsigned int num_values;
	struct ldb_val *values;
};


/**
  a ldb_message represents all or part of a record. It can contain an arbitrary
  number of elements. 
*/
struct ldb_message {
	struct ldb_dn *dn;
	unsigned int num_elements;
	struct ldb_message_element *elements;
};

enum ldb_changetype {
	LDB_CHANGETYPE_NONE=0,
	LDB_CHANGETYPE_ADD,
	LDB_CHANGETYPE_DELETE,
	LDB_CHANGETYPE_MODIFY
};

/**
  LDIF record

  This structure contains a LDIF record, as returned from ldif_read()
  and equivalent functions.
*/
struct ldb_ldif {
	enum ldb_changetype changetype; /*!< The type of change */
	struct ldb_message *msg;  /*!< The changes */
};

enum ldb_scope {LDB_SCOPE_DEFAULT=-1, 
		LDB_SCOPE_BASE=0, 
		LDB_SCOPE_ONELEVEL=1,
		LDB_SCOPE_SUBTREE=2};

struct ldb_context;

/* 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) PRINTF_ATTRIBUTE(3,0);
	void *context;
};

/**
  The user can optionally supply a custom utf8 functions,
  to handle comparisons and casefolding.
*/
struct ldb_utf8_fns {
	void *context;
	char *(*casefold)(void *context, TALLOC_CTX *mem_ctx, const char *s);
};

/**
   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

/**
   Flag value to specify autoreconnect mode.

   If LDB_FLG_RECONNECT is used in ldb_connect, then the backend will
   be opened in a way that makes it try to auto reconnect if the
   connection is dropped (actually make sense only with ldap).
*/
#define LDB_FLG_RECONNECT 4

/**
   Flag to tell backends not to use mmap
*/
#define LDB_FLG_NOMMAP 8

/*
   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,
		    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 {
			const char *attr;
			struct ldb_val value;
		} equality;
		struct {
			const char *attr;
			int start_with_wildcard;
			int end_with_wildcard;
			struct ldb_val **chunks;
		} substring;
		struct {
			const char *attr;
		} present;
		struct {
			const char *attr;
			struct ldb_val value;
		} comparison;
		struct {
			const 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(TALLOC_CTX *mem_ctx, const char *s);
char *ldb_filter_from_tree(TALLOC_CTX *mem_ctx, struct ldb_parse_tree *tree);

/**
   Encode a binary blob

   This function encodes a binary blob using the encoding rules in RFC
   2254 (Section 4). This function also escapes any non-printable
   characters.

   \param mem_ctx the memory context to allocate the return string in.
   \param val the (potentially) binary data to be encoded

   \return the encoded data as a null terminated string

   \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>.
*/
char *ldb_binary_encode(TALLOC_CTX *mem_ctx, struct ldb_val val);

/**
   Encode a string

   This function encodes a string using the encoding rules in RFC 2254
   (Section 4). This function also escapes any non-printable
   characters.

   \param mem_ctx the memory context to allocate the return string in.
   \param string the string to be encoded

   \return the encoded data as a null terminated string

   \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>.
*/
char *ldb_binary_encode_string(TALLOC_CTX *mem_ctx, const char *string);

/*
  functions for controlling attribute handling
*/
typedef int (*ldb_attr_handler_t)(struct ldb_context *, TALLOC_CTX *mem_ctx, const struct ldb_val *, struct ldb_val *);
typedef int (*ldb_attr_comparison_t)(struct ldb_context *, TALLOC_CTX *mem_ctx, const struct ldb_val *, const struct ldb_val *);

/*
  attribute handler structure

  attr			-> The attribute name
  flags			-> LDB_ATTR_FLAG_*
  ldif_read_fn		-> convert from ldif to binary format
  ldif_write_fn		-> convert from binary to ldif format
  canonicalise_fn	-> canonicalise a value, for use by indexing and dn construction
  comparison_fn		-> compare two values
*/

struct ldb_schema_syntax {
	const char *name;
	ldb_attr_handler_t ldif_read_fn;
	ldb_attr_handler_t ldif_write_fn;
	ldb_attr_handler_t canonicalise_fn;
	ldb_attr_comparison_t comparison_fn;
};

struct ldb_schema_attribute {
	const char *name;
	unsigned flags;
	const struct ldb_schema_syntax *syntax;
};

const struct ldb_schema_attribute *ldb_schema_attribute_by_name(struct ldb_context *ldb,
								const char *name);

/**
   The attribute is not returned by default
*/
#define LDB_ATTR_FLAG_HIDDEN       (1<<0) 

/* the attribute handler name should be freed when released */
#define LDB_ATTR_FLAG_ALLOCATED    (1<<1) 

/**
   The attribute is constructed from other attributes
*/
#define LDB_ATTR_FLAG_CONSTRUCTED  (1<<1) 

/**
  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.

  \sa <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) (void *v1, void *v2, void *opaque);

/**
   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"