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 ESourceGroup 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. [allow-none]

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