struct ESource

struct ESource;

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

Since 3.6

e_source_new ()

ESource *           e_source_new                        (GDBusObject *dbus_object,
                                                         GMainContext *main_context,
                                                         GError **error);

Creates a new ESource instance.

The "changed" signal will be emitted from main_context if given, or else from the thread-default GMainContext at the time this function is called.

The only time the function should be called outside of ESourceRegistry is to create a so-called "scratch" ESource for editing in a Properties window or an account setup assistant.

FIXME: Elaborate on scratch sources.

Since 3.6

e_source_new_with_uid ()

ESource *           e_source_new_with_uid               (const gchar *uid,
                                                         GMainContext *main_context,
                                                         GError **error);

Creates a new "scratch" ESource with a predetermined unique identifier.

The "changed" signal will be emitted from main_context if given, or else from the thread-default GMainContext at the time this function is called.

Since 3.6

e_source_hash ()

guint               e_source_hash                       (ESource *source);

Generates a hash value for source. This function is intended for easily hashing an ESource to add to a GHashTable or similar data structure.

Since 3.6

e_source_equal ()

gboolean            e_source_equal                      (ESource *source1,
                                                         ESource *source2);

Checks two ESource instances for equality. ESource instances are equal if their unique identifier strings are equal.

Since 3.6

e_source_changed ()

void                e_source_changed                    (ESource *source);

Emits the "changed" signal from an idle callback in source's "main-context".

This function is primarily intended for use by ESourceExtension when emitting a "notify" signal on one of its properties.

Since 3.6

e_source_get_uid ()

const gchar *       e_source_get_uid                    (ESource *source);

Returns the unique identifier string for source.

Since 3.6

e_source_dup_uid ()

gchar *             e_source_dup_uid                    (ESource *source);

Thread-safe variation of e_source_get_uid(). Use this function when accessing source from multiple threads.

The returned string should be freed with g_free() when no longer needed.

Since 3.6

e_source_get_parent ()

const gchar *       e_source_get_parent                 (ESource *source);

Returns the unique identifier string of the parent ESource.

Since 3.6

e_source_dup_parent ()

gchar *             e_source_dup_parent                 (ESource *source);

Thread-safe variation of e_source_get_parent(). Use this function when accessing source from multiple threads.

The returned string should be freed with g_free() when no longer needed.

Since 3.6

e_source_set_parent ()

void                e_source_set_parent                 (ESource *source,
                                                         const gchar *parent);

Identifies the parent of source by its unique identifier string. This can only be set prior to adding source to an ESourceRegistry.

The internal copy of "parent" is automatically stripped of leading and trailing whitespace. If the resulting string is empty, NULL is set instead.

Since 3.6

e_source_get_enabled ()

gboolean            e_source_get_enabled                (ESource *source);

Returns TRUE if source is enabled.

An application should try to honor this setting if at all possible, even if it does not provide a way to change the setting through its user interface. Disabled data sources should generally be hidden.

Since 3.6

e_source_set_enabled ()

void                e_source_set_enabled                (ESource *source,
                                                         gboolean enabled);

Enables or disables source.

An application should try to honor this setting if at all possible, even if it does not provide a way to change the setting through its user interface. Disabled data sources should generally be hidden.

Since 3.6

e_source_get_writable ()

gboolean            e_source_get_writable               (ESource *source);

Returns whether the D-Bus service will accept changes to source. If source is not writable, calls to e_source_write() will fail.

Since 3.6

e_source_get_removable ()

gboolean            e_source_get_removable              (ESource *source);

Returns whether the D-Bus service will allow source to be removed. If source is not writable, calls to e_source_remove() will fail.

Since 3.6

e_source_get_remote_creatable ()

gboolean            e_source_get_remote_creatable       (ESource *source);

Returns whether new resources can be created on a remote server by calling e_source_remote_create() on source.

Generally this is only TRUE if source has an ESourceCollection extension, which means there is an ECollectionBackend in the D-Bus service that can handle create requests. If source does not have this capability, calls to e_source_remote_create() will fail.

Since 3.6

e_source_get_remote_deletable ()

gboolean            e_source_get_remote_deletable       (ESource *source);

Returns whether the resource represented by source can be deleted from a remote server by calling e_source_remote_delete().

Generally this is only TRUE if source is a child of an ESource which has an ESourceCollection extension, which means there is an ECollectionBackend in the D-Bus service that can handle delete requests. If source does not have this capability, calls to e_source_remote_delete() will fail.

Since 3.6

e_source_get_extension ()

gpointer            e_source_get_extension              (ESource *source,
                                                         const gchar *extension_name);

Returns an instance of some ESourceExtension subclass which registered itself under extension_name. If no such instance exists within source, one will be created. It is the caller's responsibility to know which subclass is being returned.

If you just want to test for the existence of an extension within source without creating it, use e_source_has_extension().

Extension instances are owned by their ESource and should not be referenced directly. Instead, reference the ESource instance and use this function to fetch the extension instance as needed.

Since 3.6

e_source_has_extension ()

gboolean            e_source_has_extension              (ESource *source,
                                                         const gchar *extension_name);

Checks whether source has an ESourceExtension with the given name.

Since 3.6

e_source_ref_dbus_object ()

GDBusObject *       e_source_ref_dbus_object            (ESource *source);

Returns the GDBusObject that was passed to e_source_new().

The returned GDBusObject is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

Since 3.6

e_source_ref_main_context ()

GMainContext *      e_source_ref_main_context           (ESource *source);

Returns the GMainContext on which event sources for source are to be attached.

The returned GMainContext is referenced for thread-safety and must be unreferenced with g_main_context_unref() when finished with it.

Since 3.6

e_source_get_display_name ()

const gchar *       e_source_get_display_name           (ESource *source);

Returns the display name for source. Use the display name to represent the ESource in a user interface.

Since 3.6

e_source_dup_display_name ()

gchar *             e_source_dup_display_name           (ESource *source);

Thread-safe variation of e_source_get_display_name(). Use this function when accessing source from multiple threads.

The returned string should be freed with g_free() when no longer needed.

Since 3.6

e_source_set_display_name ()

void                e_source_set_display_name           (ESource *source,
                                                         const gchar *display_name);

Sets the display name for source. The display_name argument must be a valid UTF-8 string. Use the display name to represent the ESource in a user interface.

The internal copy of display_name is automatically stripped of leading and trailing whitespace.

Since 3.6

e_source_compare_by_display_name ()

gint                e_source_compare_by_display_name    (ESource *source1,
                                                         ESource *source2);

Compares two ESource instances by their display names. Useful for ordering sources in a user interface.

Since 3.6

e_source_to_string ()

gchar *             e_source_to_string                  (ESource *source,
                                                         gsize *length);

Outputs the current contents of source as a key file string. Free the returned string with g_free().

Since 3.6

e_source_parameter_to_key ()

gchar *             e_source_parameter_to_key           (const gchar *param_name);

Converts a GParamSpec name (e.g. "foo-bar" or "foo_bar") to "CamelCase" for use as a GKeyFile key (e.g. "FooBar").

This function is made public only to aid in account migration. Applications should not need to use this.

Since 3.6

e_source_remove_sync ()

gboolean            e_source_remove_sync                (ESource *source,
                                                         GCancellable *cancellable,
                                                         GError **error);

Requests the D-Bus service to delete the key files for source and all of its descendants and broadcast their removal to all clients. The source must be "removable".

If an error occurs, the functon will set error and return FALSE.

Since 3.6

e_source_remove ()

void                e_source_remove                     (ESource *source,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously requests the D-Bus service to delete the key files for source and all of its descendants and broadcast their removal to all clients. The source must be "removable".

When the operation is finished, callback will be called. You can then call e_source_remove_finish() to get the result of the operation.

Since 3.6

e_source_remove_finish ()

gboolean            e_source_remove_finish              (ESource *source,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with e_source_remove(). If an error occurred, the function will set error and return FALSE.

Since 3.6

e_source_write_sync ()

gboolean            e_source_write_sync                 (ESource *source,
                                                         GCancellable *cancellable,
                                                         GError **error);

Submits the current contents of source to the D-Bus service to be written to disk and broadcast to other clients. The source must be "writable".

If an error occurs, the functon will set error and return FALSE.

Since 3.6

e_source_write ()

void                e_source_write                      (ESource *source,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously submits the current contents of source to the D-Bus service to be written to disk and broadcast to other clients. The source must be "writable".

When the operation is finished, callback will be called. You can then call e_source_write_finish() to get the result of the operation.

Since 3.6

e_source_write_finish ()

gboolean            e_source_write_finish               (ESource *source,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with e_source_write(). If an error occurred, the function will set error and return FALSE.

Since 3.6

e_source_remote_create_sync ()

gboolean            e_source_remote_create_sync         (ESource *source,
                                                         ESource *scratch_source,
                                                         GCancellable *cancellable,
                                                         GError **error);

Creates a new remote resource by picking out relevant details from scratch_source. The scratch_source must be an ESource with no GDBusObject. The source must be "remote-creatable".

The details required to create the resource vary by ECollectionBackend, but in most cases the scratch_source need only define the resource type (address book, calendar, etc.), a display name for the resource, and possibly a server-side path or ID for the resource.

If an error occurs, the function will set error and return FALSE.

Since 3.6

e_source_remote_create ()

void                e_source_remote_create              (ESource *source,
                                                         ESource *scratch_source,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously creates a new remote resource by picking out relevant details from scratch_source. The scratch_source must be an ESource with no GDBusObject. The source must be "remote-creatable".

The details required to create the resource vary by ECollectionBackend, but in most cases the scratch_source need only define the resource type (address book, calendar, etc.), a display name for the resource, and possibly a server-side path or ID for the resource.

When the operation is finished, callback will be called. You can then call e_source_remote_create_finish() to get the result of the operation.

Since 3.6

e_source_remote_create_finish ()

gboolean            e_source_remote_create_finish       (ESource *source,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with e_source_remote_create(). If an error occurred, the function will set error and return FALSE.

Since 3.6

e_source_remote_delete_sync ()

gboolean            e_source_remote_delete_sync         (ESource *source,
                                                         GCancellable *cancellable,
                                                         GError **error);

Deletes the resource represented by source from a remote server. The source must be "remote-deletable". This will also delete the key file for source and broadcast its removal to all clients, similar to e_source_remove_sync().

If an error occurs, the function will set error and return FALSE.

Since 3.6

e_source_remote_delete ()

void                e_source_remote_delete              (ESource *source,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously deletes the resource represented by source from a remote server. The source must be "remote-deletable". This will also delete the key file for source and broadcast its removal to all clients, similar to e_source_remove().

When the operation is finished, callback will be called. You can then call e_source_remote_delete_finish() to get the result of the operation.

Since 3.6

e_source_remote_delete_finish ()

gboolean            e_source_remote_delete_finish       (ESource *source,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with e_source_remote_delete(). If an error occurred, the function will set error and return FALSE.

Since 3.6

e_source_get_oauth2_access_token_sync ()

gboolean            e_source_get_oauth2_access_token_sync
                                                        (ESource *source,
                                                         GCancellable *cancellable,
                                                         gchar **out_access_token,
                                                         gint *out_expires_in,
                                                         GError **error);

Obtains the OAuth 2.0 access token for source along with its expiry in seconds from the current time (or 0 if unknown).

Free the returned access token with g_free() when finished with it. If an error occurs, the function will set error and return FALSE.

Since 3.8

e_source_get_oauth2_access_token ()

void                e_source_get_oauth2_access_token    (ESource *source,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously obtains the OAuth 2.0 access token for source along with its expiry in seconds from the current time (or 0 if unknown).

When the operation is finished, callback will be called. You can then call e_source_get_oauth2_access_token_finish() to get the result of the operation.

Since 3.8

e_source_get_oauth2_access_token_finish ()

gboolean            e_source_get_oauth2_access_token_finish
                                                        (ESource *source,
                                                         GAsyncResult *result,
                                                         gchar **out_access_token,
                                                         gint *out_expires_in,
                                                         GError **error);

Finishes the operation started with e_source_get_oauth2_access_token().

Free the returned access token with g_free() when finished with it. If an error occurred, the function will set error and return FALSE.

Since 3.8

The "dbus-object" property

  "dbus-object"              EDBusObject*          : Read / Write / Construct Only

The D-Bus object for the data source.

The "display-name" property

  "display-name"             gchar*                : Read / Write / Construct

The human-readable name of the data source.

Default value: "Unnamed"

The "enabled" property

  "enabled"                  gboolean              : Read / Write / Construct

Whether the data source is enabled.

Default value: TRUE

The "main-context" property

  "main-context"             GMainContext*         : Read / Write / Construct Only

The main loop context on which to attach event sources.

The "parent" property

  "parent"                   gchar*                : Read / Write

The unique identity of the parent data source.

Default value: NULL

The "remote-creatable" property

  "remote-creatable"         gboolean              : Read

Whether the data source can create remote resources.

Default value: FALSE

The "remote-deletable" property

  "remote-deletable"         gboolean              : Read

Whether the data source can delete remote resources.

Default value: FALSE

The "removable" property

  "removable"                gboolean              : Read

Whether the data source is removable.

Default value: FALSE

The "uid" property

  "uid"                      gchar*                : Read / Write / Construct Only

The unique identity of the data source.

Default value: NULL

The "writable" property

  "writable"                 gboolean              : Read

Whether the data source is writable.

Default value: FALSE

The "changed" signal

void                user_function                      (ESource *source,
                                                        gpointer user_data)      : No Recursion

The ::changed signal is emitted when a property in source or one of its extension objects changes. A common use for this signal is to notify a GtkTreeModel containing data collected from ESources that it needs to update a row.