ESource

## ESource ESource — Hierarchical data sources |

## Synopsis

    #include <libedataserver/libedataserver.h>

    struct              ESource;
    ESource *           e_source_new                        (GDBusObject *dbus_object,
                                                             GMainContext *main_context,
                                                             GError **error);
    ESource *           e_source_new_with_uid               (const gchar *uid,
                                                             GMainContext *main_context,
                                                             GError **error);
    guint               e_source_hash                       (ESource *source);
    gboolean            e_source_equal                      (ESource *source1,
                                                             ESource *source2);
    void                e_source_changed                    (ESource *source);
    const gchar *       e_source_get_uid                    (ESource *source);
    gchar *             e_source_dup_uid                    (ESource *source);
    const gchar *       e_source_get_parent                 (ESource *source);
    gchar *             e_source_dup_parent                 (ESource *source);
    void                e_source_set_parent                 (ESource *source,
                                                             const gchar *parent);
    gboolean            e_source_get_enabled                (ESource *source);
    void                e_source_set_enabled                (ESource *source,
                                                             gboolean enabled);
    gboolean            e_source_get_writable               (ESource *source);
    gboolean            e_source_get_removable              (ESource *source);
    gboolean            e_source_get_remote_creatable       (ESource *source);
    gboolean            e_source_get_remote_deletable       (ESource *source);
    gpointer            e_source_get_extension              (ESource *source,
                                                             const gchar *extension_name);
    gboolean            e_source_has_extension              (ESource *source,
                                                             const gchar *extension_name);
    GDBusObject *       e_source_ref_dbus_object            (ESource *source);
    GMainContext *      e_source_ref_main_context           (ESource *source);
    const gchar *       e_source_get_display_name           (ESource *source);
    gchar *             e_source_dup_display_name           (ESource *source);
    void                e_source_set_display_name           (ESource *source,
                                                             const gchar *display_name);
    gint                e_source_compare_by_display_name    (ESource *source1,
                                                             ESource *source2);
    gchar *             e_source_to_string                  (ESource *source,
                                                             gsize *length);
    gchar *             e_source_parameter_to_key           (const gchar *param_name);
    gboolean            e_source_remove_sync                (ESource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_source_remove                     (ESource *source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_source_remove_finish              (ESource *source,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_source_write_sync                 (ESource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_source_write                      (ESource *source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_source_write_finish               (ESource *source,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_source_remote_create_sync         (ESource *source,
                                                             ESource *scratch_source,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_source_remote_create              (ESource *source,
                                                             ESource *scratch_source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_source_remote_create_finish       (ESource *source,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_source_remote_delete_sync         (ESource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_source_remote_delete              (ESource *source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_source_remote_delete_finish       (ESource *source,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_source_get_oauth2_access_token_sync
                                                            (ESource *source,
                                                             GCancellable *cancellable,
                                                             gchar **out_access_token,
                                                             gint *out_expires_in,
                                                             GError **error);
    void                e_source_get_oauth2_access_token    (ESource *source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_source_get_oauth2_access_token_finish
                                                            (ESource *source,
                                                             GAsyncResult *result,
                                                             gchar **out_access_token,
                                                             gint *out_expires_in,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----ESource

## Implemented Interfaces

ESource implements GInitable.

## Properties

      "dbus-object"              EDBusObject*          : Read / Write / Construct Only
      "display-name"             gchar*                : Read / Write / Construct
      "enabled"                  gboolean              : Read / Write / Construct
      "main-context"             GMainContext*         : Read / Write / Construct Only
      "parent"                   gchar*                : Read / Write
      "remote-creatable"         gboolean              : Read
      "remote-deletable"         gboolean              : Read
      "removable"                gboolean              : Read
      "uid"                      gchar*                : Read / Write / Construct Only
      "writable"                 gboolean              : Read

## Signals

      "changed"                                        : No Recursion

## Description

An ESource (or "data source") is a description of a file or network location where data can be obtained (such as a mail account), or a description of a resource at that location (such as a mail folder).

In more concrete terms, it's an interface for a key file. All such key files have a main group named [Data Source]. The keys in a [Data Source] group map to GObject properties in an ESource.

Additional groups in the key file are referred to as "extensions". ESourceExtension serves as the base class for writing interfaces for these additional key file groups. The keys in one of these key file groups map to GObject properties in some custom subclass of ESourceExtension which was written specifically for that key file group. For example, a key file might include a group named [Calendar], whose keys map to GObject properties in an extension class named ESourceCalendar.

Each ESource contains an internal dictionary of extension objects, accessible by their key file group name. `e_source_get_extension()` can look up extension objects by name.

An ESource is identified by a unique identifier string, or "UID", which is also the basename of the corresponding key file. Additional files related to the ESource, such as cache files, are usually kept in a directory named after the UID of the ESource. Similarly, the password for an account described by an ESource is kept in GNOME Keyring under the UID of the ESource. This makes finding these additional resources simple.

Several extensions for common information such as authentication details are built into libedataserver (ESourceAuthentication, for example). Backend modules may also define their own extensions for information and settings unique to the backend. ESourceExtension subclasses written for specific backends are generally not available to applications and shared libraries. This is by design, to try and keep backend-specific knowledge from creeping into places it doesn't belong.

## Details

### 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.

`dbus_object` : | a GDBusObject or `NULL`. [allow-none]
`main_context` : | a GMainContext or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | a new ESource, or `NULL` on error

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.

`uid` : | a new unique identifier string
`main_context` : | a GMainContext or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | a new scratch ESource, or `NULL` on error

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.

`source` : | an ESource
Returns : | a hash value for `source`.

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.

`source1` : | the first ESource
`source2` : | the second ESource
Returns : | `TRUE` if `source1` and `source2` 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.

`source` : | an ESource

Since 3.6

### e_source_get_uid ()

    const gchar *       e_source_get_uid                    (ESource *source);

Returns the unique identifier string for `source`.

`source` : | an ESource
Returns : | the UID 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.

`source` : | an ESource
Returns : | a newly-allocated copy of "uid"

Since 3.6

### e_source_get_parent ()

    const gchar *       e_source_get_parent                 (ESource *source);

Returns the unique identifier string of the parent ESource.

`source` : | an ESource
Returns : | the UID 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.

`source` : | an ESource
Returns : | a newly-allocated copy of "parent"

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.

`source` : | an ESource
`parent` : | the UID of the parent ESource, or `NULL`. [allow-none]

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.

### Note

This function does not take into account `source`'s ancestors in the ESource hierarchy, each of which have their own enabled state. If any of `source`'s ancestors are disabled, then `source` itself should be treated as disabled. Use `e_source_registry_check_enabled()` to easily check for this.

`source` : | an ESource
Returns : | whether `source` is enabled

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.

`source` : | an ESource
`enabled` : | whether to enable `source`

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.

`source` : | an ESource
Returns : | whether `source` is writable

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.

`source` : | an ESource
Returns : | whether `source` is removable

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.

`source` : | an ESource
Returns : | whether `source` can create remote resources

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.

`source` : | an ESource
Returns : | whether `source` can delete remote resources

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.

`source` : | an ESource
`extension_name` : | an extension name
Returns : | an instance of some ESourceExtension subclass. [type ESourceExtension][transfer none]

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.

`source` : | an ESource
`extension_name` : | an extension name
Returns : | `TRUE` if `source` has such an extension, `FALSE` if not

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.

`source` : | an ESource
Returns : | the GDBusObject for `source`, or `NULL`. [transfer full]

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.

`source` : | an ESource
Returns : | a GMainContext. [transfer full]

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.

`source` : | an ESource
Returns : | the display name for `source`

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.

`source` : | an ESource
Returns : | a newly-allocated copy of "display-name"

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.

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

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.

`source1` : | the first ESource
`source2` : | the second ESource
Returns : | a negative value if `source1` compares before `source2`, zero if they compare equal, or a positive value if `source1` compares after `source2`

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()`.

`source` : | an ESource
`length` : | return location for the length of the returned string, or `NULL`. [allow-none]
Returns : | a newly-allocated string

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.

`param_name` : | a GParamSpec name

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`.

`source` : | the ESource to be removed
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

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.

`source` : | the ESource to be removed
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to the callback function. [closure]

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`.

`source` : | the ESource to be removed
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` of failure

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`.

`source` : | a writable ESource
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

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.

`source` : | a writable ESource
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to the callback function. [closure]

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`.

`source` : | a writable ESource
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

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`.

`source` : | an ESource
`scratch_source` : | an ESource describing the resource to create
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

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.

`source` : | an ESource
`scratch_source` : | an ESource describing the resource to create
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to the callback function. [closure]

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`.

`source` : | an ESource
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

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`.

`source` : | an ESource
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

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.

`source` : | an ESource
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to the callback function. [closure]

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`.

`source` : | an ESource
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

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`.

`source` : | an ESource
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`out_access_token` : | return location for the access token, or `NULL`. [allow-none]
`out_expires_in` : | return location for the token expiry, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

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.

`source` : | an ESource
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to the callback function. [closure]

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`.

`source` : | an ESource
`result` : | a GAsyncResult
`out_access_token` : | return location for the access token, or `NULL`. [allow-none]
`out_expires_in` : | return location for the token expiry, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 3.8

## Property Details

### 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

## Signal Details

### 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.

`source` : | the ESource that received the signal
`user_data` : | user data set when the signal handler was connected.