ldb.h

samba最新软件

struct ldb_dn *ldb_get_schema_basedn(struct ldb_context *ldb);

/*
  return an automatic baseDN from the defaultNamingContext of the rootDSE
  This value have been set in an opaque pointer at connection time
*/
struct ldb_dn *ldb_get_default_basedn(struct ldb_context *ldb);

/**
  The default async search callback function 

  \param ldb the context associated with the database (from ldb_init())
  \param context the callback context (struct ldb_result *)
  \param ares a single reply from the async core

  \return result code (LDB_SUCCESS on success, or a failure code)

  \note this function expects the context to always be an struct ldb_result pointer
  AND a talloc context, this function will steal on the context each message
  from the ares reply passed on by the async core so that in the end all the
  messages will be in the context (ldb_result)  memory tree.
  Freeing the passed context (ldb_result tree) will free all the resources
  (the request need to be freed separately and the result doe not depend on the
  request that can be freed as sson as the search request is finished)
*/

int ldb_search_default_callback(struct ldb_context *ldb, void *context, struct ldb_reply *ares);

/**
  Helper function to build a search request

  \param ret_req the request structure is returned here (talloced on mem_ctx)
  \param ldb the context associated with the database (from ldb_init())
  \param mem_ctx a talloc memory context (used as parent of ret_req)
  \param base the Base Distinguished Name for the query (use ldb_dn_new() for an empty one)
  \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 controls an array of controls
  \param context the callback function context
  \param callback the callback function to handle the async replies

  \return result code (LDB_SUCCESS on success, or a failure code)
*/

int ldb_build_search_req(struct ldb_request **ret_req,
			struct ldb_context *ldb,
			TALLOC_CTX *mem_ctx,
			struct ldb_dn *base,
	       		enum ldb_scope scope,
			const char *expression,
			const char * const *attrs,
			struct ldb_control **controls,
			void *context,
			ldb_request_callback_t callback);

/**
  Helper function to build an add request

  \param ret_req the request structure is returned here (talloced on mem_ctx)
  \param ldb the context associated with the database (from ldb_init())
  \param mem_ctx a talloc memory context (used as parent of ret_req)
  \param message contains the entry to be added 
  \param controls an array of controls
  \param context the callback function context
  \param callback the callback function to handle the async replies

  \return result code (LDB_SUCCESS on success, or a failure code)
*/

int ldb_build_add_req(struct ldb_request **ret_req,
			struct ldb_context *ldb,
			TALLOC_CTX *mem_ctx,
			const struct ldb_message *message,
			struct ldb_control **controls,
			void *context,
			ldb_request_callback_t callback);

/**
  Helper function to build a modify request

  \param ret_req the request structure is returned here (talloced on mem_ctx)
  \param ldb the context associated with the database (from ldb_init())
  \param mem_ctx a talloc memory context (used as parent of ret_req)
  \param message contains the entry to be modified
  \param controls an array of controls
  \param context the callback function context
  \param callback the callback function to handle the async replies

  \return result code (LDB_SUCCESS on success, or a failure code)
*/

int ldb_build_mod_req(struct ldb_request **ret_req,
			struct ldb_context *ldb,
			TALLOC_CTX *mem_ctx,
			const struct ldb_message *message,
			struct ldb_control **controls,
			void *context,
			ldb_request_callback_t callback);

/**
  Helper function to build a delete request

  \param ret_req the request structure is returned here (talloced on mem_ctx)
  \param ldb the context associated with the database (from ldb_init())
  \param mem_ctx a talloc memory context (used as parent of ret_req)
  \param dn the DN to be deleted
  \param controls an array of controls
  \param context the callback function context
  \param callback the callback function to handle the async replies

  \return result code (LDB_SUCCESS on success, or a failure code)
*/

int ldb_build_del_req(struct ldb_request **ret_req,
			struct ldb_context *ldb,
			TALLOC_CTX *mem_ctx,
			struct ldb_dn *dn,
			struct ldb_control **controls,
			void *context,
			ldb_request_callback_t callback);

/**
  Helper function to build a rename request

  \param ret_req the request structure is returned here (talloced on mem_ctx)
  \param ldb the context associated with the database (from ldb_init())
  \param mem_ctx a talloc memory context (used as parent of ret_req)
  \param olddn the old DN
  \param newdn the new DN
  \param controls an array of controls
  \param context the callback function context
  \param callback the callback function to handle the async replies

  \return result code (LDB_SUCCESS on success, or a failure code)
*/

int ldb_build_rename_req(struct ldb_request **ret_req,
			struct ldb_context *ldb,
			TALLOC_CTX *mem_ctx,
			struct ldb_dn *olddn,
			struct ldb_dn *newdn,
			struct ldb_control **controls,
			void *context,
			ldb_request_callback_t callback);

/**
  Add a ldb_control to a ldb_request

  \param req the request struct where to add the control
  \param oid the object identifier of the control as string
  \param critical whether the control should be critical or not
  \param data a talloc pointer to the control specific data

  \return result code (LDB_SUCCESS on success, or a failure code)
*/
int ldb_request_add_control(struct ldb_request *req, const char *oid, bool critical, void *data);

/**
   check if a control with the specified "oid" exist and return it 
  \param req the request struct where to add the control
  \param oid the object identifier of the control as string

  \return the control, NULL if not found 
*/
struct ldb_control *ldb_request_get_control(struct ldb_request *req, const char *oid);

/**
  Search the database

  This function searches the database, and returns 
  records that match an LDAP-like search expression

  \param ldb the context associated with the database (from ldb_init())
  \param base the Base Distinguished Name for the query (use ldb_dn_new() for an empty one)
  \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, 
	       struct ldb_dn *base,
	       enum ldb_scope scope,
	       const char *expression,
	       const char * const *attrs, struct ldb_result **res);

/*
 * a useful search function where you can easily define the expression and
 * that takes a memory context where results are allocated
*/

int ldb_search_exp_fmt(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
		       struct ldb_result **result, struct ldb_dn *base,
		       enum ldb_scope scope, const char * const *attrs,
		       const char *exp_fmt, ...) PRINTF_ATTRIBUTE(7,8);

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

  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

  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, struct ldb_dn *olddn, struct ldb_dn *newdn);

/**
  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, struct ldb_dn *dn);

/**
  The default async extended operation callback function 

  \param ldb the context associated with the database (from ldb_init())
  \param context the callback context (struct ldb_result *)
  \param ares a single reply from the async core

  \return result code (LDB_SUCCESS on success, or a failure code)

  \note this function expects the context to always be an struct ldb_result pointer
  AND a talloc context, this function will steal on the context each message
  from the ares reply passed on by the async core so that in the end all the
  messages will be in the context (ldb_result)  memory tree.
  Freeing the passed context (ldb_result tree) will free all the resources
  (the request need to be freed separately and the result doe not depend on the
  request that can be freed as sson as the search request is finished)
*/
int ldb_extended_default_callback(struct ldb_context *ldb, void *context, struct ldb_reply *ares);

/**
  Helper function to build a extended request

  \param ret_req the request structure is returned here (talloced on mem_ctx)
  \param ldb the context associated with the database (from ldb_init())
  \param mem_ctx a talloc memory context (used as parent of ret_req)
  \param oid the OID of the extended operation.
  \param data a void pointer a the extended operation specific parameters,
  it needs to be NULL or a valid talloc pointer! talloc_get_type() will be used on it  
  \param controls an array of controls
  \param context the callback function context
  \param callback the callback function to handle the async replies

  \return result code (LDB_SUCCESS on success, or a failure code)
*/
int ldb_build_extended_req(struct ldb_request **ret_req,
			   struct ldb_context *ldb,
			   TALLOC_CTX *mem_ctx,
			   const char *oid,
			   void *data,/* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
			   struct ldb_control **controls,
			   void *context,
			   ldb_request_callback_t callback);

/**
  call an extended operation

  This function deletes a record from the database.

  \param ldb the context associated with the database (from ldb_init())
  \param oid the OID of the extended operation.
  \param data a void pointer a the extended operation specific parameters,
  it needs to be NULL or a valid talloc pointer! talloc_get_type() will be used on it  
  \param res the result of the extended operation

  \return result code (LDB_SUCCESS if the extended operation returned fine,
  otherwise a failure code)
*/
int ldb_extended(struct ldb_context *ldb, 
		 const char *oid,
		 void *data,/* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
		 struct ldb_result **res);

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

/**
  return a string explaining what a ldb error constant meancs
*/
const char *ldb_strerror(int ldb_err);

/**
  setup the default utf8 functions
  FIXME: these functions do not yet handle utf8
*/
void ldb_set_utf8_default(struct ldb_context *ldb);

/**
   Casefold a string

   \param ldb the ldb context
   \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

   \note The default function is not yet UTF8 aware. Provide your own
         set of functions through ldb_set_utf8_fns()
*/
char *ldb_casefold(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *s);

/**
   Check the attribute name is valid according to rfc2251
   \param s the string to check

   \return 1 if the name is ok
*/
int ldb_valid_attr_name(const char *s);

/*
  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 *, ...) PRINTF_ATTRIBUTE(2,3), 
		   void *private_data,
		   const struct ldb_ldif *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