e-named-parameters: Evolution-Data-Server Reference Manual

## e-named-parameters e-named-parameters — A structure to hold named parameters |

## Functions

ENamedParameters * | e_named_parameters_new ()
ENamedParameters * | e_named_parameters_new_strv ()
ENamedParameters * | e_named_parameters_new_string ()
ENamedParameters * | e_named_parameters_new_clone ()
void | e_named_parameters_free ()
void | e_named_parameters_clear ()
void | e_named_parameters_assign ()
void | e_named_parameters_set ()
const gchar * | e_named_parameters_get ()
gchar ** | e_named_parameters_to_strv ()
gchar * | e_named_parameters_to_string ()
gboolean | e_named_parameters_test ()
gboolean | e_named_parameters_exists ()
guint | e_named_parameters_count ()
gchar * | e_named_parameters_get_name ()
gboolean | e_named_parameters_equal ()

## Types and Values

| ENamedParameters

## Object Hierarchy

        GBoxed
        ╰── ENamedParameters

## Includes

    #include <libedataserver/libedataserver.h>

## Description

The ENamedParameters is a structure, which holds a name~>value pairs. It's usually used to pass credentials between callers.

## Functions

### e_named_parameters_new ()

    ENamedParameters *
    e_named_parameters_new (void);

Creates a new instance of an ENamedParameters. This should be freed with `e_named_parameters_free()`, when no longer needed. Names are compared case insensitively.

The structure is not thread safe, if the caller requires thread safety, then it should provide it on its own.

#### Returns

newly allocated ENamedParameters

Since: 3.8

### e_named_parameters_new_strv ()

    ENamedParameters *
    e_named_parameters_new_strv (const gchar * const *strv);

Creates a new instance of an ENamedParameters, with initial content being taken from `strv` . This should be freed with `e_named_parameters_free()`, when no longer needed. Names are compared case insensitively.

The structure is not thread safe, if the caller requires thread safety, then it should provide it on its own.

#### Parameters

strv | NULL-terminated string array to be used as a content of a newly created ENamedParameters |

#### Returns

newly allocated ENamedParameters

Since: 3.8

### e_named_parameters_new_string ()

    ENamedParameters *
    e_named_parameters_new_string (const gchar *str);

Creates a new instance of an ENamedParameters, with initial content being taken from `str` . This should be freed with `e_named_parameters_free()`, when no longer needed. Names are compared case insensitively.

The `str` should be created with `e_named_parameters_to_string()`, to be properly encoded.

The structure is not thread safe, if the caller requires thread safety, then it should provide it on its own.

#### Parameters

str | a string to be used as a content of a newly created ENamedParameters |

#### Returns

newly allocated ENamedParameters.

[transfer full]

Since: 3.18

### e_named_parameters_new_clone ()

    ENamedParameters *
    e_named_parameters_new_clone (const ENamedParameters *parameters);

Creates a new instance of an ENamedParameters, with initial content being taken from `parameters` . This should be freed with `e_named_parameters_free()`, when no longer needed. Names are compared case insensitively.

The structure is not thread safe, if the caller requires thread safety, then it should provide it on its own.

#### Parameters

parameters | an ENamedParameters to be used as a content of a newly created ENamedParameters |

#### Returns

newly allocated ENamedParameters

Since: 3.16

### e_named_parameters_free ()

    void
    e_named_parameters_free (ENamedParameters *parameters);

Frees an instance of ENamedParameters, previously allocated with `e_named_parameters_new()`. Function does nothing, if `parameters` is `NULL`.

#### Parameters

parameters | an ENamedParameters. | [nullable]

Since: 3.8

### e_named_parameters_clear ()

    void
    e_named_parameters_clear (ENamedParameters *parameters);

Removes all stored parameters from `parameters` .

#### Parameters

parameters | an ENamedParameters |

Since: 3.8

### e_named_parameters_assign ()

    void
    e_named_parameters_assign (ENamedParameters *parameters,
                               const ENamedParameters *from);

Makes content of the `parameters` the same as `from` . Functions clears content of `parameters` if `from` is `NULL`.

#### Parameters

parameters | an ENamedParameters to assign values to |
from | an ENamedParameters to get values from, or `NULL`. | [nullable]

Since: 3.8

### e_named_parameters_set ()

    void
    e_named_parameters_set (ENamedParameters *parameters,
                            const gchar *name,
                            const gchar *value);

Sets parameter named `name` to value `value` . If `value` is NULL, then the parameter is removed. `value` can be an empty string.

Note: There is a restriction on parameter names, it cannot be empty or contain a colon character (':'), otherwise it can be pretty much anything.

#### Parameters

parameters | an ENamedParameters |
name | name of a parameter to set |
value | value to set, or `NULL` to unset. | [nullable]

Since: 3.8

### e_named_parameters_get ()

    const gchar *
    e_named_parameters_get (const ENamedParameters *parameters,
                            const gchar *name);

Returns current value of a parameter with name `name` . If not such exists, then returns `NULL`.

#### Parameters

parameters | an ENamedParameters |
name | name of a parameter to get |

#### Returns

value of a parameter named `name` , or `NULL`.

[nullable]

Since: 3.8

### e_named_parameters_to_strv ()

    gchar **
    e_named_parameters_to_strv (const ENamedParameters *parameters);

#### Parameters

parameters | an ENamedParameters |

#### Returns

Contents of `parameters` as a null-terminated strv.

[transfer full]

Since: 3.8

### e_named_parameters_to_string ()

    gchar *
    e_named_parameters_to_string (const ENamedParameters *parameters);

#### Parameters

parameters | an ENamedParameters |

#### Returns

Contents of `parameters` as a string.

[transfer full][nullable]

Since: 3.18

### e_named_parameters_test ()

    gboolean
    e_named_parameters_test (const ENamedParameters *parameters,
                             const gchar *name,
                             const gchar *value,
                             gboolean case_sensitively);

Compares current value of parameter named `name` with given `value` and returns whether they are equal, either case sensitively or insensitively, based on `case_sensitively` argument. Function returns `FALSE`, if no such parameter exists.

#### Parameters

parameters | an ENamedParameters |
name | name of a parameter to test |
value | value to test |
case_sensitively | whether to compare case sensitively |

#### Returns

Whether parameter of given name has stored value of given value.

Since: 3.8

### e_named_parameters_exists ()

    gboolean
    e_named_parameters_exists (const ENamedParameters *parameters,
                               const gchar *name);

#### Parameters

parameters | an ENamedParameters |
name | name of the parameter whose existence to check |

#### Returns

Whether `parameters` holds a parameter named `name`

Since: 3.18

### e_named_parameters_count ()

    guint
    e_named_parameters_count (const ENamedParameters *parameters);

#### Parameters

parameters | an ENamedParameters |

#### Returns

The number of stored named parameters in `parameters`

Since: 3.18

### e_named_parameters_get_name ()

    gchar *
    e_named_parameters_get_name (const ENamedParameters *parameters,
                                 gint index);

#### Parameters

parameters | an ENamedParameters |
index | an index of the parameter whose name to retrieve |

#### Returns

The name of the parameters at index `index` , or `NULL`, of the `index` is out of bounds or other error. The returned string should be freed with `g_free()` when done with it.

[transfer full][nullable]

Since: 3.18

### e_named_parameters_equal ()

    gboolean
    e_named_parameters_equal (const ENamedParameters *parameters1,
                              const ENamedParameters *parameters2);

Compares the two parameters objects and returns whether they equal. Note a `NULL` and empty parameters are also considered equal.

#### Parameters

parameters1 | the first ENamedParameters |
parameters2 | the second ENamedParameters |

#### Returns

whether the two parameters are equal

Since: 3.46

## Types and Values

### ENamedParameters

    typedef struct _ENamedParameters ENamedParameters;

Since: 3.8