## GdaLdapConnection GdaLdapConnection — LDAP connection objects |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <virtual/gda-ldap-connection.h>

    struct              GdaLdapConnection;
    struct              GdaLdapConnectionClass;
                        GdaLdapConnectionPrivate;
    const gchar *       gda_ldap_connection_get_base_dn     (GdaLdapConnection *cnc);
    gboolean            gda_ldap_connection_declare_table   (GdaLdapConnection *cnc,
                                                             const gchar *table_name,
                                                             const gchar *base_dn,
                                                             const gchar *filter,
                                                             const gchar *attributes,
                                                             GdaLdapSearchScope scope,
                                                             GError **error);
    gboolean            gda_ldap_connection_undeclare_table (GdaLdapConnection *cnc,
                                                             const gchar *table_name,
                                                             GError **error);

                        GdaLdapAttribute;
                        GdaLdapEntry;
    gboolean            gda_ldap_is_dn                      (const gchar *dn);
    gchar **            gda_ldap_dn_split                   (const gchar *dn,
                                                             gboolean all);
    GdaLdapEntry *      gda_ldap_describe_entry             (GdaLdapConnection *cnc,
                                                             const gchar *dn,
                                                             GError **error);
    void                gda_ldap_entry_free                 (GdaLdapEntry *entry);
    GdaLdapEntry **     gda_ldap_get_entry_children         (GdaLdapConnection *cnc,
                                                             const gchar *dn,
                                                             gchar **attributes,
                                                             GError **error);

    void                gda_ldap_entry_add_attribute        (GdaLdapEntry *entry,
                                                             gboolean merge,
                                                             const gchar *attr_name,
                                                             guint nb_values,
                                                             GValue **values);
    GdaLdapEntry *      gda_ldap_entry_new                  (const gchar *dn);
                        GdaLdapAttributeDefinition;
    GSList *            gda_ldap_entry_get_attributes_list  (GdaLdapConnection *cnc,
                                                             GdaLdapEntry *entry);
    void                gda_ldap_attributes_list_free       (GSList *list);

    enum                GdaLdapModificationType;
    gboolean            gda_ldap_add_entry                  (GdaLdapConnection *cnc,
                                                             GdaLdapEntry *entry,
                                                             GError **error);
    gboolean            gda_ldap_remove_entry               (GdaLdapConnection *cnc,
                                                             const gchar *dn,
                                                             GError **error);
    gboolean            gda_ldap_rename_entry               (GdaLdapConnection *cnc,
                                                             const gchar *current_dn,
                                                             const gchar *new_dn,
                                                             GError **error);
    gboolean            gda_ldap_modify_entry               (GdaLdapConnection *cnc,
                                                             GdaLdapModificationType modtype,
                                                             GdaLdapEntry *entry,
                                                             GdaLdapEntry *ref_entry,
                                                             GError **error);

    enum                GdaLdapClassKind;
                        GdaLdapClass;
    GdaLdapClass *      gda_ldap_get_class_info             (GdaLdapConnection *cnc,
                                                             const gchar *classname);
    const GSList *      gda_ldap_get_top_classes            (GdaLdapConnection *cnc);

## Object Hierarchy

      GObject
       +----GdaConnection
             +----GdaVirtualConnection
                   +----GdaVconnectionDataModel
                         +----GdaLdapConnection

## Implemented Interfaces

GdaLdapConnection implements GdaLockable.

## Properties

      "startup-file"             gchar*                : Read / Write

## Description

This is a connection, as opened by the LDAP provider. Use `gda_connection_open_from_string()` or `gda_connection_open_from_dsn()` to create a GdaLdapConnection connection.

Warning: if you create a GdaLdapConnection using `g_object_new()`, then the resulting object won't be functionnal.

A GdaLdapConnection is a virtual connection which accepts any of SQLite's SQL dialect. However, some SQL commands have been added to manipulate virtual tables mapped to LDAP searches. These commands are:

- The CREATE LDAP TABLE:

      CREATE LDAP TABLE <table name> [BASE=<base DN>] [FILTER=<LDAP filter>] [ATTRIBUTES=<LDAP attributes>] [SCOPE=<search scope>]

  Each of the BASE, FILTER, ATTRIBUTES and SCOPE specifications is optional. Use this command to declare a table, for example:

      CREATE LDAP TABLE users FILTER='(cn=*doe*)' SCOPE= 'SUBTREE';

  . The allowed SCOPE values are: 'BASE', 'ONELEVEL' and 'SUBTREE'.

  See the `gda_ldap_connection_declare_table()` for more information about the ATTRIBUTES syntax.

- The DROP LDAP TABLE:

      DROP LDAP TABLE <table name>

  Use this command to undeclare a table, for example:

      DROP LDAP TABLE users;

  Note that it is also possible to use the normal command to remove a table:

      DROP TABLE users;

- The ALTER LDAP TABLE:

      ALTER LDAP TABLE <table name>

  or

      ALTER LDAP TABLE <table name> [BASE=<base DN>] [FILTER=<LDAP filter>] [ATTRIBUTES=<LDAP attributes>] [SCOPE=<search scope>]

  Use this command to modify the definition of a virtual table, for example:

      ALTER LDAP TABLE users FILTER='(cn=*doe*)' SCOPE='BASE';

  If no argument is specified after the table name, then the definition of the virtual table is returned instead. When altering the virtual table, only the specified parameters are altered (ie. you don't need to repeat the parameters you don't want to be modified)

- The DESCRIBE LDAP TABLE:

      DESCRIBE LDAP TABLE <table name>

  Use this command to get the definition of the virtual table.

Each "LDAP" table can then be used like any other table, but you should keep in mind that Libgda can optimize the LDAP search command executed when the table's data is actually read if you use a "WHERE" clause which involves a search criteria on an LDAP attribute. For example the following SQL:

    SELECT * FROM users WHERE cn MATCH '%doe%';

will actually be optimized by requesting an LDAP search with the filter

    (cn=*doe*)

Optimizations can be done on MATCH, =, <, <=, > and >= operators, the LIKE operator will not be optimized.

However a command like

    SELECT * FROM users WHERE cn MATCH '%doe%' OR uid=123;

can't be optimized (because of the "OR") whereas the

    SELECT * FROM users WHERE cn MATCH '%doe%' AND uid=123;

will be optimized because of the "AND".

## Details

### struct GdaLdapConnection

    struct GdaLdapConnection;

### struct GdaLdapConnectionClass

    struct GdaLdapConnectionClass {
    	GdaVconnectionDataModelClass parent_class;
    };

### GdaLdapConnectionPrivate

    typedef struct _GdaLdapConnectionPrivate GdaLdapConnectionPrivate;

### gda_ldap_connection_get_base_dn ()

    const gchar *       gda_ldap_connection_get_base_dn     (GdaLdapConnection *cnc);

Get the base DN which was used when the LDAP connection was opened

`cnc` : | a GdaLdapConnection
Returns : | the base DN, or `NULL`

Since 4.2.8

### gda_ldap_connection_declare_table ()

    gboolean            gda_ldap_connection_declare_table   (GdaLdapConnection *cnc,
                                                             const gchar *table_name,
                                                             const gchar *base_dn,
                                                             const gchar *filter,
                                                             const gchar *attributes,
                                                             GdaLdapSearchScope scope,
                                                             GError **error);

Declare a virtual table based on an LDAP search.

The `filter` argument, if not `NULL`, must be a valid LDAP filter string (including the opening and closing parenthesis).

The `attribute`, if not `NULL`, is a list of comma separated LDAP entry attribute names. For each attribute it is also possible to specify a requested GType, and how to behave in case of multi valued attributes So the general format for an attribute is: "<attribute name>[::<type>][::<muti value handler>]", where:

- "::<type>" is optional, see `gda_g_type_from_string()` for more information about valie values for <type>

- "::<muti value handler>" is also optional and specifies how a multi values attributed is treated. The possibilities for <muti value handler> are:

  - "NULL" or "0": a NULL value will be returned

  - "CSV": a comma separated value with all the values of the attribute will be returned. This only works for G_TYPE_STRING attribute types.

  - "MULT" of "*": a row will be returned for each value of the attribute, effectively multiplying the number of returned rows

  - "1": only the first vakue of the attribute will be used, the other values ignored

  - "CONCAT": the attributes' values are concatenated (with a newline char between each value)

  - "ERROR": an error value will be returned (this is the default behaviour)

After each attribute name (and before the comma for the next attribute if any), it is possible to specify the GType type using the "::<type>" syntax (see `gda_g_type_from_string()` for more information).

The following example specifies the "uidNumber" attribute to be returned as a string, the "mail" attribute, and the "objectClass" attribute to be handled as one row per value of that attribute:

    "uidNumber::string,mail,objectClass::*"

`cnc` : | a GdaLdapConnection
`table_name` : | a table name, not `NULL`
`base_dn` : | the base DN of the LDAP search, or `NULL` for `cnc`'s own base DN. [allow-none]
`filter` : | the search filter of the LDAP search, or `NULL` for a default filter of "(ObjectClass=*)". [allow-none]
`attributes` : | the search attributes of the LDAP search, or `NULL` if only the DN is required. [allow-none]
`scope` : | the search scope of the LDAP search
`error` : | a place to store errors, or `NULL`
Returns : | `TRUE` if no error occurred

Since 4.2.8

### gda_ldap_connection_undeclare_table ()

    gboolean            gda_ldap_connection_undeclare_table (GdaLdapConnection *cnc,
                                                             const gchar *table_name,
                                                             GError **error);

Remove a table which has been declared using `gda_ldap_connection_declare_table()`.

`cnc` : | a GdaLdapConnection
`table_name` : | a table name, not `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | `TRUE` if no error occurred

Since 4.2.8

### GdaLdapAttribute

    typedef struct {
    	gchar   *attr_name;
    	guint    nb_values;
    	GValue **values;
    } GdaLdapAttribute;

This structure holds information about the values of a single attribute (of a single LDAP entry).

gchar *`attr_name`; | the name of the attribute
guint `nb_values`; | the number of values in `values`, or `0`
GValue **`values`; | the attribute' values as GValue values, (terminated by a `NULL`). [allow-none][array length=nb_values][array zero-terminated=1]

### GdaLdapEntry

    typedef struct {
    	gchar             *dn;
    	guint              nb_attributes;
    	GdaLdapAttribute **attributes;
    	GHashTable        *attributes_hash;
    } GdaLdapEntry;

This structure holds information about the attributes of a single LDAP entry.

gchar *`dn`; | the Distinguished Name of the entry
guint `nb_attributes`; | the number of attributes in `attributes`, or `0`
GdaLdapAttribute **`attributes`; | the entry's attributes, (terminated by a `NULL`). [allow-none][array length=nb_attributes][array zero-terminated=1]
GHashTable *`attributes_hash`; | a hash table where the key is an attribute name, and the value the correcponding GdaLdapAttribute

### gda_ldap_is_dn ()

    gboolean            gda_ldap_is_dn                      (const gchar *dn);

Tells if `dn` represents a distinguished name (it only checks for the syntax, not for the actual existence of the entry with that distinguished name).

`dn` : | a Distinguished Name string
Returns : | `TRUE` if `dn` is a valid representation of a distinguished name

Since 4.2.8

### gda_ldap_dn_split ()

    gchar **            gda_ldap_dn_split                   (const gchar *dn,
                                                             gboolean all);

Splits `dn` into its components.

`dn` : | a Distinguished Name string
`all` : | set to `FALSE` to split `dn` into its RND and its parent DN, or `TRUE` to completely split `dn`
Returns : | a `NULL` terminated array containing the DN parts (free using `g_strfreev()`), or `NULL` if an error occurred because `dn` is not a valid DN expression. [transfer full][Free-function: g_strfreev]

Since 4.2.8

### gda_ldap_describe_entry ()

    GdaLdapEntry *      gda_ldap_describe_entry             (GdaLdapConnection *cnc,
                                                             const gchar *dn,
                                                             GError **error);

Describes the LDAP entry which DN is `dn`. If `dn` is `NULL`, then the top entry (as specified when the LDAP connection was opened) is described.

`cnc` : | a GdaLdapConnection connection
`dn` : | the Distinguished Name of the LDAP entry to describe. [allow-none]
`error` : | a place to store errors, or `NULL`. [allow-none]
Returns : | a new GdaLdapEntry, or `NULL` if an error occurred or if the `dn` entry does not exist. [transfer full][Free-function: gda_ldap_entry_free]

Since 4.2.8

### gda_ldap_entry_free ()

    void                gda_ldap_entry_free                 (GdaLdapEntry *entry);

Frees `entry`

`entry` : | a GdaLdapEntry pointer. [transfer full]

Since 4.2.8

### gda_ldap_get_entry_children ()

    GdaLdapEntry **     gda_ldap_get_entry_children         (GdaLdapConnection *cnc,
                                                             const gchar *dn,
                                                             gchar **attributes,
                                                             GError **error);

Get the list of children entries for the LDAP entry which DN is `dn`. If the `dn` entry does not have any child, then this function returns an array which first element is `NULL`.

If `dn` is `NULL`, then the top entry (as specified when the LDAP connection was opened) is used.

`cnc` : | a GdaLdapConnection connection
`dn` : | the Distinguished Name of the LDAP entry to get children from. [allow-none]
`attributes` : | a `NULL` terminated array of attributes to fetch for each child, or `NULL` if no attribute is requested. [allow-none][array zero-terminated=1][element-type gchar*]
`error` : | a place to store errors, or `NULL`. [allow-none]
Returns : | a `NULL` terminated array of GdaLdapEntry for each child entry, or `NULL` if an error occurred or if the `dn` entry does not exist. [transfer full][element_type GdaLdapEntry][array zero-terminated=1]

Since 4.2.8

### gda_ldap_entry_add_attribute ()

    void                gda_ldap_entry_add_attribute        (GdaLdapEntry *entry,
                                                             gboolean merge,
                                                             const gchar *attr_name,
                                                             guint nb_values,
                                                             GValue **values);

Add an attribute (ans its values) to `entry`. If the attribute is already present in `entry`, then the attribute's values are merged or replaced depending on the `merge` argument.

`entry` : | a GdaLdapEntry pointer
`merge` : | set to `TRUE` to merge the values in case of an existing attribute in `entry`, and `FALSE` to replace any existing attribute's values in `entry`
`attr_name` : | the name of the attribute to add
`nb_values` : | number of values in `values`
`values` : | an array of GValue (as much values as specified by `nb_values`). [array length=nb_values]

Since 5.2.0

### gda_ldap_entry_new ()

    GdaLdapEntry *      gda_ldap_entry_new                  (const gchar *dn);

Creates a new GdaLdapEntry. This function is useful when using `gda_ldap_modify_entry()`

`dn` : | a Distinguished name, or `NULL`. [allow-none]
Returns : | a new GdaLdapEntry

Since 5.2.0

### GdaLdapAttributeDefinition

    typedef struct {
    	gchar   *name;
    	GType    g_type;
    	gboolean required;
    } GdaLdapAttributeDefinition;

### gda_ldap_entry_get_attributes_list ()

    GSList *            gda_ldap_entry_get_attributes_list  (GdaLdapConnection *cnc,
                                                             GdaLdapEntry *entry);

Get a list of all the possible attributes which `entry` can have. Each possible attribute is represented by a GdaLdapAttributeDefinition strunture.

`cnc` : | a GdaLdapConnection
`entry` : | a GdaLdapEntry
Returns : | a GSList of GdaLdapAttributeDefinition pointers, free the list using `gda_ldap_attributes_list_free()`. [transfer full][element-type GdaLdapAttributeDefinition]

Since 5.2.0

### gda_ldap_attributes_list_free ()

    void                gda_ldap_attributes_list_free       (GSList *list);

Frees the list returned by `gda_ldap_entry_get_attributes_list()`.

`list` : | a GSList of GdaLdapAttributeDefinition pointers, or `NULL`. [allow-none]

Since 5.2.0

### enum GdaLdapModificationType

    typedef enum {
    	GDA_LDAP_MODIFICATION_INSERT,
    	GDA_LDAP_MODIFICATION_DELETE,
    	GDA_LDAP_MODIFICATION_ATTR_ADD,
    	GDA_LDAP_MODIFICATION_ATTR_DEL,
    	GDA_LDAP_MODIFICATION_ATTR_REPL,
    	GDA_LDAP_MODIFICATION_ATTR_DIFF
    } GdaLdapModificationType;

Speficies the type of operation requested when writing to an LDAP directory.

`GDA_LDAP_MODIFICATION_INSERT` | modification corresponds to a new LDAP entry
`GDA_LDAP_MODIFICATION_DELETE` | modification corresponds to removing an LDAP entry
`GDA_LDAP_MODIFICATION_ATTR_ADD` | modification correspond to adding attributes to an existing LDAP entry
`GDA_LDAP_MODIFICATION_ATTR_DEL` | modification correspond to removing attributes from an existing LDAP entry
`GDA_LDAP_MODIFICATION_ATTR_REPL` | modification correspond to replacing attributes of an existing LDAP entry
`GDA_LDAP_MODIFICATION_ATTR_DIFF` | modification correspond to modifying attributes to an existing LDAP entry

### gda_ldap_add_entry ()

    gboolean            gda_ldap_add_entry                  (GdaLdapConnection *cnc,
                                                             GdaLdapEntry *entry,
                                                             GError **error);

Creates a new LDAP entry.

`cnc` : | a GdaLdapConnection
`entry` : | a GdaLDapEntry describing the LDAP entry to add
`error` : | a place to store an error, or `NULL`. [allow-none]
Returns : | `TRUE` if no error occurred

Since 5.2.0

### gda_ldap_remove_entry ()

    gboolean            gda_ldap_remove_entry               (GdaLdapConnection *cnc,
                                                             const gchar *dn,
                                                             GError **error);

Delete an LDAP entry.

`cnc` : | a GdaLdapConnection
`entry` : | a GdaLDapEntry describing the LDAP entry to remove
`error` : | a place to store an error, or `NULL`. [allow-none]
Returns : | `TRUE` if no error occurred

Since 5.2.0

### gda_ldap_rename_entry ()

    gboolean            gda_ldap_rename_entry               (GdaLdapConnection *cnc,
                                                             const gchar *current_dn,
                                                             const gchar *new_dn,
                                                             GError **error);

Renames an LDAP entry.

`cnc` : | a GdaLdapConnection
`current_dn` : | the current DN of the entry
`new_dn` : | the new DN of the entry
`error` : | a place to store an error, or `NULL`. [allow-none]
Returns : | `TRUE` if no error occurred

Since 5.2.0

### gda_ldap_modify_entry ()

    gboolean            gda_ldap_modify_entry               (GdaLdapConnection *cnc,
                                                             GdaLdapModificationType modtype,
                                                             GdaLdapEntry *entry,
                                                             GdaLdapEntry *ref_entry,
                                                             GError **error);

Modifies an LDAP entry.

`cnc` : | a GdaLdapConnection
`modtype` : | the type of modification to perform
`entry` : | a GdaLDapEntry describing the LDAP entry to apply modifications, along with the attributes which will be modified
`ref_entry` : | a GdaLDapEntry describing the reference LDAP entry, if `modtype` is `GDA_LDAP_MODIFICATION_ATTR_DIFF`. [allow-none]
`error` : | a place to store an error, or `NULL`. [allow-none]
Returns : | `TRUE` if no error occurred

Since 5.2.0

### enum GdaLdapClassKind

    typedef enum {
    	GDA_LDAP_CLASS_KIND_ABSTRACT  = 1,
    	GDA_LDAP_CLASS_KIND_STRUTURAL = 2,
    	GDA_LDAP_CLASS_KIND_AUXILIARY = 3,
    	GDA_LDAP_CLASS_KIND_UNKNOWN   = 4
    } GdaLdapClassKind;

Defines the LDAP class type

`GDA_LDAP_CLASS_KIND_ABSTRACT` | the LDAP class is an abstract class
`GDA_LDAP_CLASS_KIND_STRUTURAL` | the LDAP class is a structural class
`GDA_LDAP_CLASS_KIND_AUXILIARY` | the LDAP class is auxilliary
`GDA_LDAP_CLASS_KIND_UNKNOWN` | the LDAP class type is not known

### GdaLdapClass

    typedef struct {
    	gchar            *oid;
    	guint             nb_names; /* always >= 1 */
    	gchar           **names;
    	gchar            *description;
    	GdaLdapClassKind  kind;
    	gboolean          obsolete;

    	guint             nb_req_attributes;
    	gchar           **req_attributes;
    	guint             nb_opt_attributes;
    	gchar           **opt_attributes;

    	GSList           *parents; /* list of #GdaLdapClass */
    	GSList           *children; /* list of #GdaLdapClass */
    } GdaLdapClass;

Represents an LDAP declared class.

gchar *`oid`; | the OID of the class
guint `nb_names`; | the number of values in `values` (always >= 1)
gchar **`names`; | all the class names
gchar *`description`; | the class's description, or `NULL`. [allow-none]
GdaLdapClassKind `kind`; | the class kind
gboolean `obsolete`; | defines is LDAP class is obsolete
guint `nb_req_attributes`; | the number of values in `req_attributes`
gchar **`req_attributes`; | names of required attributes in class
guint `nb_opt_attributes`; | the number of values in `opt_attributes`
gchar **`opt_attributes`; | names of optional attributes in class
GSList *`parents`; | GSList of the parent classes (pointers to GdaLdapClass)
GSList *`children`; | GSList of the children classes (pointers to GdaLdapClass)

### gda_ldap_get_class_info ()

    GdaLdapClass *      gda_ldap_get_class_info             (GdaLdapConnection *cnc,
                                                             const gchar *classname);

Get information about an LDAP class

`cnc` : | a GdaLdapConnection
`classname` : | an LDAP class name
Returns : | a GdaLdapClass. [transfer none]

Since 4.2.8

### gda_ldap_get_top_classes ()

    const GSList *      gda_ldap_get_top_classes            (GdaLdapConnection *cnc);

get a list of the top level LDAP classes (ie. classes which don't have any parent)

`cnc` : | a GdaLdapConnection
Returns : | a list of GdaLdapClass pointers (don't modify it). [transfer none][element-type GdaLdapClass]

Since 4.2.8

## Property Details

### The `"startup-file"` property

      "startup-file"             gchar*                : Read / Write

File used to store startup data.

Default value: NULL