ldb.h

samba最新软件

   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(TALLOC_CTX *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);

/* The following definitions come from lib/ldb/common/ldb_dn.c  */

struct ldb_dn *ldb_dn_new(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *dn);
struct ldb_dn *ldb_dn_new_fmt(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *new_fmt, ...) PRINTF_ATTRIBUTE(3,4);
bool ldb_dn_validate(struct ldb_dn *dn);

char *ldb_dn_escape_value(TALLOC_CTX *mem_ctx, struct ldb_val value);
const char *ldb_dn_get_linearized(struct ldb_dn *dn);
const char *ldb_dn_get_casefold(struct ldb_dn *dn);
char *ldb_dn_alloc_linearized(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
char *ldb_dn_alloc_casefold(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);

int ldb_dn_compare_base(struct ldb_dn *base, struct ldb_dn *dn);
int ldb_dn_compare(struct ldb_dn *edn0, struct ldb_dn *edn1);

bool ldb_dn_add_base(struct ldb_dn *dn, struct ldb_dn *base);
bool ldb_dn_add_base_fmt(struct ldb_dn *dn, const char *base_fmt, ...) PRINTF_ATTRIBUTE(2,3);
bool ldb_dn_add_child(struct ldb_dn *dn, struct ldb_dn *child);
bool ldb_dn_add_child_fmt(struct ldb_dn *dn, const char *child_fmt, ...) PRINTF_ATTRIBUTE(2,3);
bool ldb_dn_remove_base_components(struct ldb_dn *dn, unsigned int num);
bool ldb_dn_remove_child_components(struct ldb_dn *dn, unsigned int num);

struct ldb_dn *ldb_dn_copy(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
struct ldb_dn *ldb_dn_get_parent(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
char *ldb_dn_canonical_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
char *ldb_dn_canonical_ex_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
int ldb_dn_get_comp_num(struct ldb_dn *dn);
const char *ldb_dn_get_component_name(struct ldb_dn *dn, unsigned int num);
const struct ldb_val *ldb_dn_get_component_val(struct ldb_dn *dn, unsigned int num);
const char *ldb_dn_get_rdn_name(struct ldb_dn *dn);
const struct ldb_val *ldb_dn_get_rdn_val(struct ldb_dn *dn);
int ldb_dn_set_component(struct ldb_dn *dn, int num, const char *name, const struct ldb_val val);

bool ldb_dn_is_valid(struct ldb_dn *dn);
bool ldb_dn_is_special(struct ldb_dn *dn);
bool ldb_dn_check_special(struct ldb_dn *dn, const char *check);
bool ldb_dn_is_null(struct ldb_dn *dn);


/**
   Compare two attributes

   This function compares to attribute names. Note that this is a
   case-insensitive comparison.

   \param a the first attribute name to compare
   \param b 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

  attribute names are restricted by rfc2251 so using
  strcasecmp and toupper here is ok.
  return 0 for match
*/
#define ldb_attr_cmp(a, b) strcasecmp(a, b)
char *ldb_attr_casefold(TALLOC_CTX *mem_ctx, const char *s);
int ldb_attr_dn(const char *attr);

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

   \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

   \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
*/
int ldb_msg_add_empty(struct ldb_message *msg,
		const char *attr_name,
		int flags,
		struct ldb_message_element **return_el);

/**
   add a element to a ldb_message
*/
int ldb_msg_add(struct ldb_message *msg, 
		const struct ldb_message_element *el, 
		int flags);
int ldb_msg_add_value(struct ldb_message *msg, 
		const char *attr_name,
		const struct ldb_val *val,
		struct ldb_message_element **return_el);
int ldb_msg_add_steal_value(struct ldb_message *msg, 
		      const char *attr_name,
		      struct ldb_val *val);
int ldb_msg_add_steal_string(struct ldb_message *msg, 
			     const char *attr_name, char *str);
int ldb_msg_add_string(struct ldb_message *msg, 
		       const char *attr_name, const char *str);
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
*/
int ldb_msg_element_compare(struct ldb_message_element *el1, 
			    struct ldb_message_element *el2);

/**
   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.
*/
const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name);
int ldb_msg_find_attr_as_int(const struct ldb_message *msg, 
			     const char *attr_name,
			     int default_value);
unsigned int ldb_msg_find_attr_as_uint(const struct ldb_message *msg, 
				       const char *attr_name,
				       unsigned int default_value);
int64_t ldb_msg_find_attr_as_int64(const struct ldb_message *msg, 
				   const char *attr_name,
				   int64_t default_value);
uint64_t ldb_msg_find_attr_as_uint64(const struct ldb_message *msg, 
				     const char *attr_name,
				     uint64_t default_value);
double ldb_msg_find_attr_as_double(const struct ldb_message *msg, 
				   const char *attr_name,
				   double default_value);
int ldb_msg_find_attr_as_bool(const struct ldb_message *msg, 
			      const char *attr_name,
			      int default_value);
const char *ldb_msg_find_attr_as_string(const struct ldb_message *msg, 
					const char *attr_name,
					const char *default_value);

struct ldb_dn *ldb_msg_find_attr_as_dn(struct ldb_context *ldb,
				       TALLOC_CTX *mem_ctx,
				       const struct ldb_message *msg,
				       const char *attr_name);

void ldb_msg_sort_elements(struct ldb_message *msg);

struct ldb_message *ldb_msg_copy_shallow(TALLOC_CTX *mem_ctx, 
					 const struct ldb_message *msg);
struct ldb_message *ldb_msg_copy(TALLOC_CTX *mem_ctx, 
				 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);

int ldb_msg_check_string_attribute(const struct ldb_message *msg,
				   const char *name,
				   const char *value);

/**
   Integrity check an ldb_message

   This function performs basic sanity / integrity checks on an
   ldb_message.

   \param ldb context in which to perform the checks
   \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(struct ldb_context *ldb,
			 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(TALLOC_CTX *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) PRINTF_ATTRIBUTE(3,0),
		  void *context);

/**
  this allows the user to set custom utf8 function for error reporting
*/
void ldb_set_utf8_fns(struct ldb_context *ldb,
			void *context,
			char *(*casefold)(void *, void *, const char *));

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

const char **ldb_attr_list_copy(TALLOC_CTX *mem_ctx, const char * const *attrs);
const char **ldb_attr_list_copy_add(TALLOC_CTX *mem_ctx, const char * const *attrs, const char *new_attr);
int ldb_attr_in_list(const char * const *attrs, const char *attr);


void ldb_parse_tree_attr_replace(struct ldb_parse_tree *tree, 
				 const char *attr, 
				 const char *replace);

int ldb_msg_rename_attr(struct ldb_message *msg, const char *attr, const char *replace);
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
   GeneralizedTime 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(TALLOC_CTX *mem_ctx, time_t t);

/**
   Convert a string to a time structure

   This function converts an LDAP formatted GeneralizedTime 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);

/**
   Convert a time structure to a string

   This function converts a time_t structure to an LDAP formatted
   UTCTime 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_utc(TALLOC_CTX *mem_ctx, time_t t);

/**
   Convert a string to a time structure

   This function converts an LDAP formatted UTCTime 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_utc_to_time(const char *s);


void ldb_qsort (void *const pbase, size_t total_elems, size_t size, void *opaque, ldb_qsort_cmp_fn_t cmp);


/**
   Convert an array of string represention of a control into an array of ldb_control structures 
   
   \param ldb LDB context
   \param mem_ctx TALLOC context to return result on, and to allocate error_string on
   \param control_strings Array of string-formatted controls

   \return array of ldb_control elements
*/
struct ldb_control **ldb_parse_control_strings(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char **control_strings);

#endif