Difference between revisions of "Samba4/LDB/API"

From SambaWiki
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
= DN =
+
= Initialization =
   
== ldb_dn_get_linearized() ==
+
== ldb_global_init() ==
   
  +
int ldb_global_init(void);
const char *ldb_dn_get_linearized(struct ldb_dn *dn);
 
   
  +
Initialise ldbs' global information
Get the linear form of a DN (without any extended components)
 
   
  +
This is required before any other LDB call
Parameters:
 
* dn: The DN to linearize
 
 
== ldb_dn_alloc_linearized() ==
 
 
char *ldb_dn_alloc_linearized(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
 
 
Allocate a copy of the linear form of a DN (without any extended components) onto the supplied memory context
 
 
Parameters:
 
* dn: The DN to linearize
 
* mem_ctx: TALLOC context to return result on
 
 
== ldb_dn_get_extended_linearized() ==
 
 
char *ldb_dn_get_extended_linearized(void *mem_ctx, struct ldb_dn *dn, int mode);
 
 
Get the linear form of a DN (with any extended components)
 
 
Parameters:
 
* mem_ctx: TALLOC context to return result on
 
* dn: The DN to linearize
 
* mode: Style of extended DN to return (0 is HEX representation of binary form, 1 is a string form)
 
 
== ldb_dn_get_extended_component() ==
 
 
const struct ldb_val *ldb_dn_get_extended_component(struct ldb_dn *dn, const char *name);
 
 
== ldb_dn_set_extended_component() ==
 
 
int ldb_dn_set_extended_component(struct ldb_dn *dn, const char *name, const struct ldb_val *val);
 
 
== ldb_dn_remove_extended_components() ==
 
 
void ldb_dn_remove_extended_components(struct ldb_dn *dn);
 
 
== ldb_dn_has_extended() ==
 
 
bool ldb_dn_has_extended(struct ldb_dn *dn);
 
   
  +
Return: 0 if initialisation succeeded, -1 otherwise
== ldb_dn_extended_add_syntax() ==
 
   
  +
== ldb_init() ==
int ldb_dn_extended_add_syntax(struct ldb_context *ldb, unsigned flags, const struct ldb_dn_extended_syntax *syntax);
 
   
  +
struct ldb_context *ldb_init(TALLOC_CTX *mem_ctx, struct tevent_context *ev_ctx);
== ldb_dn_new() ==
 
   
  +
Initialise an ldb context
struct ldb_dn *ldb_dn_new(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *dn);
 
   
  +
This is required before any other LDB call.
Allocate a new DN from a string
 
   
 
Parameters:
 
Parameters:
* mem_ctx: TALLOC context to return resulting ldb_dn structure on
+
* mem_ctx: pointer to a talloc memory context. Pass NULL if there is no suitable context available.
* dn: The new DN
 
   
  +
Return: pointer to ldb_context that should be free'd (using talloc_free()) at the end of the program.
The DN will not be parsed at this time. Use ldb_dn_validate to tell if the DN is syntacticly correct
 
   
  +
= Connection =
== ldb_dn_new_fmt() ==
 
   
  +
== ldb_connect() ==
struct ldb_dn *ldb_dn_new_fmt(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *new_fmt, ...) PRINTF_ATTRIBUTE(3,4);
 
   
  +
int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);
Allocate a new DN from a printf style format string and arguments
 
   
  +
Connect to a database.
Parameters:
 
* mem_ctx: TALLOC context to return resulting ldb_dn structure on
 
* new_fms: The new DN as a format string (plus arguments)
 
   
  +
This is typically called soon after ldb_init(), and is required prior to any search or database modification operations.
The DN will not be parsed at this time. Use ldb_dn_validate to tell if the DN is syntacticly correct
 
   
  +
The URL can be one of the following forms:
== ldb_dn_from_ldb_val() ==
 
  +
* tdb://path
 
  +
* ldapi://path
struct ldb_dn *ldb_dn_from_ldb_val(void *mem_ctx, struct ldb_context *ldb, const struct ldb_val *strdn);
 
  +
* ldap://host
 
  +
* sqlite://path
Allocate a new DN from a struct ldb_val (useful to avoid buffer overrun)
 
   
 
Parameters:
 
Parameters:
* mem_ctx: TALLOC context to return resulting ldb_dn structure on
+
* ldb: the context associated with the database (from ldb_init())
  +
* url: the URL of the database to connect to, as noted above
* dn: The new DN
 
  +
* flags: a combination of LDB_FLG_* to modify the connection behaviour
  +
* options: backend specific options - passed uninterpreted to the backend
   
  +
Return: result code (LDB_SUCCESS on success, or a failure code)
The DN will not be parsed at this time. Use ldb_dn_validate to tell if the DN is syntacticly correct
 
   
  +
It is an error to connect to a database that does not exist in readonly mode
== ldb_dn_validate() ==
 
  +
(that is, with LDB_FLG_RDONLY). However in read-write mode, the database will be
  +
created if it does not exist.
   
  +
= Root DSE =
bool ldb_dn_validate(struct ldb_dn *dn);
 
   
  +
== ldb_get_root_basedn() ==
Determine if this DN is syntactically valid
 
   
  +
struct ldb_dn *ldb_get_root_basedn(struct ldb_context *ldb);
Parameters:
 
* dn: The DN to validate
 
   
  +
Return: an automatic basedn from the rootDomainNamingContext of the rootDSE.
== ldb_dn_escape_value() ==
 
  +
This value have been set in an opaque pointer at connection time
   
  +
== ldb_get_config_basedn() ==
char *ldb_dn_escape_value(TALLOC_CTX *mem_ctx, struct ldb_val value);
 
   
  +
struct ldb_dn *ldb_get_config_basedn(struct ldb_context *ldb);
== ldb_dn_get_casefold() ==
 
   
  +
Return: an automatic basedn from the configurationNamingContext of the rootDSE.
const char *ldb_dn_get_casefold(struct ldb_dn *dn);
 
  +
This value have been set in an opaque pointer at connection time
   
== ldb_dn_alloc_casefold() ==
+
== ldb_get_schema_basedn() ==
   
  +
struct ldb_dn *ldb_get_schema_basedn(struct ldb_context *ldb);
char *ldb_dn_alloc_casefold(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
 
   
  +
Return: an automatic basedn from the schemaNamingContext of the rootDSE.
== ldb_dn_compare_base() ==
 
  +
This value have been set in an opaque pointer at connection time
   
  +
== ldb_get_default_basedn() ==
int ldb_dn_compare_base(struct ldb_dn *base, struct ldb_dn *dn);
 
   
  +
struct ldb_dn *ldb_get_default_basedn(struct ldb_context *ldb);
== ldb_dn_compare() ==
 
   
  +
Return: an automatic baseDN from the defaultNamingContext of the rootDSE. This value have been set in an opaque pointer at connection time.
int ldb_dn_compare(struct ldb_dn *edn0, struct ldb_dn *edn1);
 
   
  +
= Attributes =
== ldb_dn_add_base() ==
 
   
  +
== ldb_attr_cmp() ==
bool ldb_dn_add_base(struct ldb_dn *dn, struct ldb_dn *base);
 
   
  +
#define ldb_attr_cmp(a, b) strcasecmp(a, b)
== ldb_dn_add_base_fmt() ==
 
   
  +
Compare two attributes
bool ldb_dn_add_base_fmt(struct ldb_dn *dn, const char *base_fmt, ...) PRINTF_ATTRIBUTE(2,3);
 
   
  +
This function compares to attribute names. Note that this is a case-insensitive comparison.
== ldb_dn_add_child() ==
 
   
  +
Parameters:
bool ldb_dn_add_child(struct ldb_dn *dn, struct ldb_dn *child);
 
  +
* a: the first attribute name to compare
  +
* 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
== ldb_dn_add_child_fmt() ==
 
   
  +
attribute names are restricted by rfc2251 so using strcasecmp and toupper here is ok. return 0 for match
bool ldb_dn_add_child_fmt(struct ldb_dn *dn, const char *child_fmt, ...) PRINTF_ATTRIBUTE(2,3);
 
   
== ldb_dn_remove_base_components() ==
+
== ldb_attr_casefold() ==
   
  +
char *ldb_attr_casefold(TALLOC_CTX *mem_ctx, const char *s);
bool ldb_dn_remove_base_components(struct ldb_dn *dn, unsigned int num);
 
   
== ldb_dn_remove_child_components() ==
+
== ldb_attr_dn() ==
   
  +
int ldb_attr_dn(const char *attr);
bool ldb_dn_remove_child_components(struct ldb_dn *dn, unsigned int num);
 
   
  +
= LDAP Operations =
== ldb_dn_copy() ==
 
   
  +
== ldb_search() ==
struct ldb_dn *ldb_dn_copy(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
 
   
  +
int ldb_search(struct ldb_context *ldb, TALLOC_CTX *mem_ctx,
== ldb_dn_get_parent() ==
 
  +
struct ldb_result **result, struct ldb_dn *base,
  +
enum ldb_scope scope, const char * const *attrs,
  +
const char *exp_fmt, ...) PRINTF_ATTRIBUTE(7,8);
   
  +
Search the database
struct ldb_dn *ldb_dn_get_parent(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
 
   
  +
This function searches the database, and returns records that match an LDAP-like search expression
== ldb_dn_canonical_string() ==
 
   
  +
Parameters:
char *ldb_dn_canonical_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
 
  +
* ldb the: context associated with the database (from ldb_init())
  +
* mem_ctx: the memory context to use for the request and the results
  +
* result: the return result
  +
* base: the Base Distinguished Name for the query (use ldb_dn_new() for an empty one)
  +
* scope: the search scope for the query
  +
* attrs: the search attributes for the query (pass NULL if none required)
  +
* exp_fmt: the search expression to use for this query (printf like)
   
  +
Return: result code (LDB_SUCCESS on success, or a failure code)
== ldb_dn_canonical_ex_string() ==
 
   
  +
Note: Use talloc_free() to free the ldb_result returned.
char *ldb_dn_canonical_ex_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
 
   
== ldb_dn_get_comp_num() ==
+
== ldb_add() ==
   
int ldb_dn_get_comp_num(struct ldb_dn *dn);
+
int ldb_add(struct ldb_context *ldb,
  +
const struct ldb_message *message);
   
  +
Add a record to the database.
== ldb_dn_get_component_name() ==
 
   
  +
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.
const char *ldb_dn_get_component_name(struct ldb_dn *dn, unsigned int num);
 
   
  +
Parameters:
== ldb_dn_get_component_val() ==
 
  +
* ldb: the context associated with the database (from ldb_init())
  +
* message: the message containing the record to add.
   
  +
Return: result code (LDB_SUCCESS if the record was added, otherwise a failure code)
const struct ldb_val *ldb_dn_get_component_val(struct ldb_dn *dn, unsigned int num);
 
   
== ldb_dn_get_rdn_name() ==
+
== ldb_modify() ==
   
const char *ldb_dn_get_rdn_name(struct ldb_dn *dn);
+
int ldb_modify(struct ldb_context *ldb,
  +
const struct ldb_message *message);
   
  +
Modify the specified attributes of a record
== ldb_dn_get_rdn_val() ==
 
   
  +
This function modifies a record that is in the database.
const struct ldb_val *ldb_dn_get_rdn_val(struct ldb_dn *dn);
 
   
  +
Parameters:
== ldb_dn_set_component() ==
 
  +
* ldb: the context associated with the database (from ldb_init())
  +
* 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_dn_set_component(struct ldb_dn *dn, int num, const char *name, const struct ldb_val val);
 
   
== ldb_dn_is_valid() ==
+
== ldb_rename() ==
   
bool ldb_dn_is_valid(struct ldb_dn *dn);
+
int ldb_rename(struct ldb_context *ldb, struct ldb_dn *olddn, struct ldb_dn *newdn);
   
  +
Rename a record in the database
== ldb_dn_is_special() ==
 
   
  +
This function renames a record in the database.
bool ldb_dn_is_special(struct ldb_dn *dn);
 
   
  +
Parameters:
== ldb_dn_check_special() ==
 
  +
* ldb: the context associated with the database (from ldb_init())
  +
* olddn: the DN for the record to be renamed.
  +
* newdn: the new DN
   
  +
Return: result code (LDB_SUCCESS if the record was renamed as requested, otherwise a failure code)
bool ldb_dn_check_special(struct ldb_dn *dn, const char *check);
 
   
== ldb_dn_is_null() ==
+
== ldb_delete() ==
   
bool ldb_dn_is_null(struct ldb_dn *dn);
+
int ldb_delete(struct ldb_context *ldb, struct ldb_dn *dn);
   
  +
Delete a record from the database
== ldb_attr_cmp() ==
 
   
  +
This function deletes a record from the database.
#define ldb_attr_cmp(a, b) strcasecmp(a, b)
 
 
Compare two attributes
 
 
This function compares to attribute names. Note that this is a case-insensitive comparison.
 
   
 
Parameters:
 
Parameters:
  +
* ldb: the context associated with the database (from ldb_init())
* a: the first attribute name to compare
 
* b: the second attribute name to compare
+
* dn: the DN for the record to be deleted.
   
  +
Return: result code (LDB_SUCCESS if the record was deleted, otherwise a failure code)
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
 
 
== ldb_attr_casefold() ==
 
 
char *ldb_attr_casefold(TALLOC_CTX *mem_ctx, const char *s);
 
 
== ldb_attr_dn() ==
 
 
int ldb_attr_dn(const char *attr);
 

Latest revision as of 17:19, 24 September 2009

Initialization

ldb_global_init()

int ldb_global_init(void);

Initialise ldbs' global information

This is required before any other LDB call

Return: 0 if initialisation succeeded, -1 otherwise

ldb_init()

struct ldb_context *ldb_init(TALLOC_CTX *mem_ctx, struct tevent_context *ev_ctx);

Initialise an ldb context

This is required before any other LDB call.

Parameters:

  • 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.

Connection

ldb_connect()

int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]);

Connect to a database.

This is typically called soon after ldb_init(), and is required prior to any search or database modification operations.

The URL can be one of the following forms:

  • tdb://path
  • ldapi://path
  • ldap://host
  • sqlite://path

Parameters:

  • ldb: the context associated with the database (from ldb_init())
  • url: the URL of the database to connect to, as noted above
  • flags: a combination of LDB_FLG_* to modify the connection behaviour
  • options: backend specific options - passed uninterpreted to the backend

Return: result code (LDB_SUCCESS on success, or a failure code)

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.

Root DSE

ldb_get_root_basedn()

struct ldb_dn *ldb_get_root_basedn(struct ldb_context *ldb);

Return: an automatic basedn from the rootDomainNamingContext of the rootDSE. This value have been set in an opaque pointer at connection time

ldb_get_config_basedn()

struct ldb_dn *ldb_get_config_basedn(struct ldb_context *ldb);

Return: an automatic basedn from the configurationNamingContext of the rootDSE. This value have been set in an opaque pointer at connection time

ldb_get_schema_basedn()

struct ldb_dn *ldb_get_schema_basedn(struct ldb_context *ldb);

Return: an automatic basedn from the schemaNamingContext of the rootDSE. This value have been set in an opaque pointer at connection time

ldb_get_default_basedn()

struct ldb_dn *ldb_get_default_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.

Attributes

ldb_attr_cmp()

#define ldb_attr_cmp(a, b) strcasecmp(a, b)

Compare two attributes

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

Parameters:

  • a: the first attribute name to compare
  • 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

ldb_attr_casefold()

char *ldb_attr_casefold(TALLOC_CTX *mem_ctx, const char *s);

ldb_attr_dn()

int ldb_attr_dn(const char *attr);

LDAP Operations

ldb_search()

int ldb_search(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);

Search the database

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

Parameters:

  • ldb the: context associated with the database (from ldb_init())
  • mem_ctx: the memory context to use for the request and the results
  • result: the return result
  • base: the Base Distinguished Name for the query (use ldb_dn_new() for an empty one)
  • scope: the search scope for the query
  • attrs: the search attributes for the query (pass NULL if none required)
  • exp_fmt: the search expression to use for this query (printf like)

Return: result code (LDB_SUCCESS on success, or a failure code)

Note: Use talloc_free() to free the ldb_result returned.

ldb_add()

int ldb_add(struct ldb_context *ldb, 
    const struct ldb_message *message);

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.

Parameters:

  • ldb: the context associated with the database (from ldb_init())
  • message: the message containing the record to add.

Return: result code (LDB_SUCCESS if the record was added, otherwise a failure code)

ldb_modify()

int ldb_modify(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.

Parameters:

  • ldb: the context associated with the database (from ldb_init())
  • message: the message containing the changes required.

Return: result code (LDB_SUCCESS if the record was modified as requested, otherwise a failure code)

ldb_rename()

int ldb_rename(struct ldb_context *ldb, struct ldb_dn *olddn, struct ldb_dn *newdn);

Rename a record in the database

This function renames a record in the database.

Parameters:

  • ldb: the context associated with the database (from ldb_init())
  • olddn: the DN for the record to be renamed.
  • newdn: the new DN

Return: result code (LDB_SUCCESS if the record was renamed as requested, otherwise a failure code)

ldb_delete()

int ldb_delete(struct ldb_context *ldb, struct ldb_dn *dn);

Delete a record from the database

This function deletes a record from the database.

Parameters:

  • ldb: the context associated with the database (from ldb_init())
  • dn: the DN for the record to be deleted.

Return: result code (LDB_SUCCESS if the record was deleted, otherwise a failure code)