## ESource

ESource

## Synopsis

    struct              ESource;
    ESource *           e_source_new                        (const gchar *name,
                                                             const gchar *relative_uri);
    ESource *           e_source_new_with_absolute_uri      (const gchar *name,
                                                             const gchar *absolute_uri);
    ESource *           e_source_new_from_xml_node          (xmlNodePtr node);
    ESource *           e_source_new_from_standalone_xml    (const gchar *xml);
    ESource *           e_source_copy                       (ESource *source);
    gboolean            e_source_update_from_xml_node       (ESource *source,
                                                             xmlNodePtr node,
                                                             gboolean *changed_return);
    gchar *             e_source_uid_from_xml_node          (xmlNodePtr node);
    void                e_source_set_group                  (ESource *source,
                                                             struct _ESourceGroup *group);
    void                e_source_set_name                   (ESource *source,
                                                             const gchar *name);
    void                e_source_set_relative_uri           (ESource *source,
                                                             const gchar *relative_uri);
    void                e_source_set_absolute_uri           (ESource *source,
                                                             const gchar *absolute_uri);
    void                e_source_set_color_spec             (ESource *source,
                                                             const gchar *color_spec);
    void                e_source_set_readonly               (ESource *source,
                                                             gboolean readonly);
    struct _ESourceGroup * e_source_peek_group              (ESource *source);
    const gchar *       e_source_peek_uid                   (ESource *source);
    const gchar *       e_source_peek_name                  (ESource *source);
    const gchar *       e_source_peek_relative_uri          (ESource *source);
    const gchar *       e_source_peek_absolute_uri          (ESource *source);
    const gchar *       e_source_peek_color_spec            (ESource *source);
    gboolean            e_source_get_readonly               (ESource *source);
    gchar *             e_source_get_uri                    (ESource *source);
    void                e_source_dump_to_xml_node           (ESource *source,
                                                             xmlNodePtr parent_node);
    gchar *             e_source_to_standalone_xml          (ESource *source);
    const gchar *       e_source_get_property               (ESource *source,
                                                             const gchar *property_name);
    void                e_source_set_property               (ESource *source,
                                                             const gchar *property_name,
                                                             const gchar *property_value);
    void                e_source_foreach_property           (ESource *source,
                                                             GHFunc func,
                                                             gpointer user_data);
    gchar *             e_source_get_duped_property         (ESource *source,
                                                             const gchar *property_name);
    gchar *             e_source_build_absolute_uri         (ESource *source);
    gboolean            e_source_equal                      (ESource *a,
                                                             ESource *b);
    gboolean            e_source_xmlstr_equal               (const gchar *a,
                                                             const gchar *b);

## Object Hierarchy

      GObject
       +----ESource

## Signals

      "changed"                                        : Run Last

## Description

## Details

### struct ESource

    struct ESource;

Contains only private data that should be read and manipulated using the functions below.

### e_source_new ()

    ESource *           e_source_new                        (const gchar *name,
                                                             const gchar *relative_uri);

Creates a new ESource instance, and gives it a display name specified by `name` and a relative URI specified by `relative_uri`.

`name` : | a display name for the source
`relative_uri` : | a relative URI for the source
Returns : | a new ESource

### e_source_new_with_absolute_uri ()

    ESource *           e_source_new_with_absolute_uri      (const gchar *name,
                                                             const gchar *absolute_uri);

Creates a new ESource instance, and gives it a display name specified by `name` and a custom absolute URI specified by `abolute_uri`.

`name` : | a display name for the source
`absolute_uri` : | a custom absolute URI for the source
Returns : | a new ESource

### e_source_new_from_xml_node ()

    ESource *           e_source_new_from_xml_node          (xmlNodePtr node);

Creates a new ESource instance from the XML specification in `node`. If the XML specification is invalid, the function returns `NULL`.

`node` : | a pointer to the XML node to parse
Returns : | a new ESource, or `NULL`

### e_source_new_from_standalone_xml ()

    ESource *           e_source_new_from_standalone_xml    (const gchar *xml);

Constructs an ESource instance from an XML string representation, probably generated by `e_source_to_standalone_xml()`.

`xml` : | an XML representation of an ESource
Returns : | a new ESource

### e_source_copy ()

    ESource *           e_source_copy                       (ESource *source);

Creates a new ESource instance from `source`, such that passing `source` and the newly created instance to `e_source_equal()` would return `TRUE`.

`source` : | an ESource
Returns : | a newly-created ESource. [transfer full]

### e_source_update_from_xml_node ()

    gboolean            e_source_update_from_xml_node       (ESource *source,
                                                             xmlNodePtr node,
                                                             gboolean *changed_return);

Update the ESource attributes from `node`. If `changed_return` is non-`NULL`, it will be set to `TRUE` if any attributes were actually changed in the course of the update. This will also emit the "changed" signal if any attributes were actually changed.

`source` : | an ESource.
`node` : | a pointer to the XML node to parse
`changed_return` : | return location for change confirmation, or `NULL`
Returns : | `TRUE` if the data in `node` was recognized and parsed into acceptable values for `source`, `FALSE` otherwise

### e_source_uid_from_xml_node ()

    gchar *             e_source_uid_from_xml_node          (xmlNodePtr node);

Assuming that `node` is a valid ESource specification, retrieve the source's unique identifier string from it. Free the returned string with `g_free()`.

`node` : | a pointer to an XML node
Returns : | the unique ID of the source specified by `node`, or `NULL` if `node` is not a valid specification

### e_source_set_group ()

    void                e_source_set_group                  (ESource *source,
                                                             struct _ESourceGroup *group);

If the read-only flag for `source` is set, the function does nothing.

Otherwise, sets the group membership for `source`.

<note> <para> If you want to add an ESource to an ESourceGroup, use `e_source_group_add_source()`. This function only notifies `source` of its group membership, but makes no effort to verify that membership with `group`. </para> </note>

This will emit the "changed" signal if the group membership actually changed.

`source` : | an ESource
`group` : | an ESourceGroup

### e_source_set_name ()

    void                e_source_set_name                   (ESource *source,
                                                             const gchar *name);

If the read-only flag for `source` is set, the function does nothing.

Otherwise, sets the display name for `source`.

This will emit the "changed" signal if the display name actually changed.

`source` : | an ESource
`name` : | a display name

### e_source_set_relative_uri ()

    void                e_source_set_relative_uri           (ESource *source,
                                                             const gchar *relative_uri);

If the read-only flag for `source` is set, the function does nothing.

Otherwise, sets the relative URI for `source`. If `source` is a member of an ESourceGroup and has not been given a custom absolute URI, the function also generates a new absolute URI for `source`.

This will emit the "changed" signal if the relative URI actually changed.

`source` : | an ESource
`relative_uri` : | a relative URI string

### e_source_set_absolute_uri ()

    void                e_source_set_absolute_uri           (ESource *source,
                                                             const gchar *absolute_uri);

Sets a custom absolute URI for `source`. If `absolute_uri` is `NULL`, the custom absolute URI is cleared and `source` will fall back to its relative URI plus the base URI of its containing ESourceGroup.

This will emit the "changed" signal if the custom absolute URI actually changed.

`source` : | an ESource
`absolute_uri` : | an absolute URI string, or `NULL`

### e_source_set_color_spec ()

    void                e_source_set_color_spec             (ESource *source,
                                                             const gchar *color_spec);

Store a textual representation of a color in `source`. The `color_spec` string should be parsable by #`gdk_color_parse()`, or `NULL` to unset the color in `source`.

This will emit the "changed" signal if the color representation actually changed.

`source` : | an ESource
`color_spec` : | a string specifying the color

Since 1.10

### e_source_set_readonly ()

    void                e_source_set_readonly               (ESource *source,
                                                             gboolean readonly);

Sets `source` as being read-only (`TRUE`) or writable (`FALSE`). A read-only ESource ignores attempts to change its display name, ESourceGroup, relative URI or color.

This will emit the "changed" signal if the read-only state actually changed.

`source` : | an ESource
`readonly` : | a read-only flag

### e_source_peek_group ()

    struct _ESourceGroup * e_source_peek_group              (ESource *source);

Returns the ESourceGroup to which `source` belongs, or `NULL` if it does not belong to a group.

`source` : | an ESource
Returns : | the group to which the source belongs. [transfer none]

### e_source_peek_uid ()

    const gchar *       e_source_peek_uid                   (ESource *source);

Returns the unique identifier string for `source`.

`source` : | an ESource
Returns : | the source's unique ID

### e_source_peek_name ()

    const gchar *       e_source_peek_name                  (ESource *source);

Returns the display name for `source`.

`source` : | an ESource
Returns : | the source's display name

### e_source_peek_relative_uri ()

    const gchar *       e_source_peek_relative_uri          (ESource *source);

Returns the relative URI for `source`.

`source` : | an ESource
Returns : | the source's relative URI

### e_source_peek_absolute_uri ()

    const gchar *       e_source_peek_absolute_uri          (ESource *source);

Returns the absolute URI for `source` if it has one, or else `NULL` if it has only a relative URI. `e_source_get_uri()` may be more convenient.

`source` : | an ESource
Returns : | the source's own absolute URI, or `NULL`

### e_source_peek_color_spec ()

    const gchar *       e_source_peek_color_spec            (ESource *source);

Return the textual representation of the color for `source`, or `NULL` if it has none. The returned string should be parsable by #`gdk_color_parse()`.

`source` : | an ESource
Returns : | a string specifying the color

Since 1.10

### e_source_get_readonly ()

    gboolean            e_source_get_readonly               (ESource *source);

Returns the read-only flag for `source`.

`source` : | an ESource
Returns : | `TRUE` if the source is read-only, `FALSE` if it's writable

### e_source_get_uri ()

    gchar *             e_source_get_uri                    (ESource *source);

Returns a newly-allocated copy of an absolute URI for `source`. If `source` has no absolute URI of its own, the URI is constructed from the base URI of its ESourceGroup and its relative URI. Free the returned string with `g_free()`.

`source` : | an ESource
Returns : | a newly-allocated absolute URI string

### e_source_dump_to_xml_node ()

    void                e_source_dump_to_xml_node           (ESource *source,
                                                             xmlNodePtr parent_node);

Converts `source` to an <structname>xmlNode</structname> structure and adds it as a child of `parent_node`.

`source` : | an ESource
`parent_node` : | location to add XML data

### e_source_to_standalone_xml ()

    gchar *             e_source_to_standalone_xml          (ESource *source);

Converts `source` to an XML string for permanent storage. Free the returned string with `g_free()`.

`source` : | an ESource
Returns : | a newly-allocated XML string

### e_source_get_property ()

    const gchar *       e_source_get_property               (ESource *source,
                                                             const gchar *property_name);

Looks up the value of a custom ESource property. If no such property name exists in `source`, the function returns `NULL`.

`source` : | an ESource
`property_name` : | a custom property name
Returns : | the property value, or `NULL`

### e_source_set_property ()

    void                e_source_set_property               (ESource *source,
                                                             const gchar *property_name,
                                                             const gchar *property_value);

Create a new custom ESource property or replaces an existing one. If `property_value` is `NULL`, the property is removed from `source`. This will also emit a "changed" signal.

`source` : | an ESource
`property_name` : | a custom property name
`property_value` : | a new value for the property, or `NULL`

### e_source_foreach_property ()

    void                e_source_foreach_property           (ESource *source,
                                                             GHFunc func,
                                                             gpointer user_data);

Calls the given function for each property in `source`. The function is passed the name and value of each property, and the given `user_data` argument. The properties may not be modified while iterating over them.

`source` : | an ESource
`func` : | the function to call for each property. [scope call]
`user_data` : | user data to pass to the function

### e_source_get_duped_property ()

    gchar *             e_source_get_duped_property         (ESource *source,
                                                             const gchar *property_name);

Looks up the value of a custom ESource property and returns a newly-allocated copy of the value. If no such property name exists in `source`, the function returns `NULL`. Free the returned value with `g_free()`.

`source` : | an ESource
`property_name` : | a custom property name
Returns : | a newly-allocated copy of the property value, or `NULL`

Since 1.12

### e_source_build_absolute_uri ()

    gchar *             e_source_build_absolute_uri         (ESource *source);

Builds an absolute URI string using the base URI of the ESourceGroup to which `source` belongs, and its own relative URI. This function ignores any custom absolute URIs set with `e_source_set_absolute_uri()`. Free the returned string with `g_free()`.

`source` : | an ESource
Returns : | a newly-allocated absolute URI string

### e_source_equal ()

    gboolean            e_source_equal                      (ESource *a,
                                                             ESource *b);

Compares if `a` is equivalent to `b`.

`a` : | an ESource
`b` : | another ESource
Returns : | `TRUE` if `a` is equivalent to `b`, `FALSE` otherwise

Since 2.24

### e_source_xmlstr_equal ()

    gboolean            e_source_xmlstr_equal               (const gchar *a,
                                                             const gchar *b);

Compares if `a` is equivalent to `b`.

`a` : | an XML representation of an ESource
`b` : | an XML representation of another ESource
Returns : | `TRUE` if `a` is equivalent to `b`, `FALSE` otherwise

Since 2.24

## Signal Details

### The `"changed"` signal

    void                user_function                      (ESource *esource,
                                                            gpointer user_data)      : Run Last

`esource` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.