ESourceRefresh: Evolution-Data-Server Reference Manual

## ESourceRefresh ESourceRefresh — ESource extension for refresh settings |

## Functions

void | (*ESourceRefreshFunc) ()
gboolean | e_source_refresh_get_enabled ()
void | e_source_refresh_set_enabled ()
gboolean | e_source_refresh_get_enabled_on_metered_network ()
void | e_source_refresh_set_enabled_on_metered_network ()
guint | e_source_refresh_get_interval_minutes ()
void | e_source_refresh_set_interval_minutes ()
guint | e_source_refresh_add_timeout ()
void | e_source_refresh_force_timeout ()
gboolean | e_source_refresh_remove_timeout ()
guint | e_source_refresh_remove_timeouts_by_data ()

## Types and Values

#define | E_SOURCE_EXTENSION_REFRESH
struct | ESourceRefresh

## Object Hierarchy

        GObject
        ╰── ESourceExtension
            ╰── ESourceRefresh

## Includes

    #include <libedataserver/libedataserver.h>

## Description

The ESourceRefresh extension tracks the interval for fetching updates from a remote server.

Access the extension as follows:

    1
    2
    3
    4
    5
    #include <libedataserver/libedataserver.h>

    ESourceRefresh *extension;

    extension = e_source_get_extension (source, E_SOURCE_EXTENSION_REFRESH);

## Functions

### ESourceRefreshFunc ()

    void
    (*ESourceRefreshFunc) (ESource *source,
                           gpointer user_data);

#### Parameters

source | an ESource |
user_data | user data provided to the callback function |

Since: 3.6

### e_source_refresh_get_enabled ()

    gboolean
    e_source_refresh_get_enabled (ESourceRefresh *extension);

Returns whether to periodically fetch updates from a remote server.

The refresh interval is determined by the “interval-minutes” property.

#### Parameters

extension | an ESourceRefresh |

#### Returns

whether periodic refresh is enabled

Since: 3.6

### e_source_refresh_set_enabled ()

    void
    e_source_refresh_set_enabled (ESourceRefresh *extension,
                                  gboolean enabled);

Sets whether to periodically fetch updates from a remote server.

The refresh interval is determined by the “interval-minutes” property.

#### Parameters

extension | an ESourceRefresh |
enabled | whether to enable periodic refresh |

Since: 3.6

### e_source_refresh_get_enabled_on_metered_network ()

    gboolean
    e_source_refresh_get_enabled_on_metered_network
                                   (ESourceRefresh *extension);

Returns whether can refresh content on metered network.

The `extension` itself doesn't use this option, it's up to the `extension` user to determine what kind of connection is used and then decide whether refresh, or other expensive network operations, can be done.

#### Parameters

extension | an ESourceRefresh |

#### Returns

whether can refresh content on metered network

Since: 3.50

### e_source_refresh_set_enabled_on_metered_network ()

    void
    e_source_refresh_set_enabled_on_metered_network
                                   (ESourceRefresh *extension,
                                    gboolean enabled);

Sets whether can refresh content on metered network.

See `e_source_refresh_get_enabled_on_metered_network()` for more information about what it means.

#### Parameters

extension | an ESourceRefresh |
enabled | whether can refresh content on metered network |

Since: 3.50

### e_source_refresh_get_interval_minutes ()

    guint
    e_source_refresh_get_interval_minutes (ESourceRefresh *extension);

Returns the interval for fetching updates from a remote server.

Note this value is only effective when the “enabled” property is `TRUE`.

#### Parameters

extension | an ESourceRefresh |

#### Returns

the interval in minutes

Since: 3.6

### e_source_refresh_set_interval_minutes ()

    void
    e_source_refresh_set_interval_minutes (ESourceRefresh *extension,
                                           guint interval_minutes);

Sets the interval for fetching updates from a remote server.

Note this value is only effective when the “enabled” property is `TRUE`.

#### Parameters

extension | an ESourceRefresh |
interval_minutes | the interval in minutes |

Since: 3.6

### e_source_refresh_add_timeout ()

    guint
    e_source_refresh_add_timeout (ESource *source,
                                  GMainContext *context,
                                  ESourceRefreshFunc callback,
                                  gpointer user_data,
                                  GDestroyNotify notify);

This is a simple way to schedule a periodic data source refresh.

Adds a timeout GSource to `context` and handles all the bookkeeping if `source` 's refresh “enabled” state or its refresh “interval-minutes” value changes. The `callback` is expected to dispatch an asynchronous job to connect to and fetch updates from a remote server.

The returned ID can be passed to `e_source_refresh_remove_timeout()` to remove the timeout from `context` . Note the ID is a private handle and cannot be passed to `g_source_remove()`.

#### Parameters

source | an ESource |
context | a GMainContext, or `NULL` (if `NULL`, the default context will be used). | [nullable]
callback | function to call on each timeout |
user_data | data to pass to `callback` |
notify | function to call when the timeout is removed, or `NULL`. | [nullable]

#### Returns

a refresh timeout ID

Since: 3.6

### e_source_refresh_force_timeout ()

    void
    e_source_refresh_force_timeout (ESource *source);

For all timeouts added with `e_source_refresh_add_timeout()`, invokes the ESourceRefreshFunc callback immediately and then, if the refresh “enabled” state is TRUE, reschedules the timeout.

This function is called automatically when the ESource switches from disabled to enabled, but can also be useful when a network connection becomes available or when waking up from hibernation or suspend.

#### Parameters

source | an ESource |

Since: 3.6

### e_source_refresh_remove_timeout ()

    gboolean
    e_source_refresh_remove_timeout (ESource *source,
                                     guint refresh_timeout_id);

Removes a timeout GSource added by `e_source_refresh_add_timeout()`.

#### Parameters

source | an ESource |
refresh_timeout_id | a refresh timeout ID |

#### Returns

`TRUE` if the timeout was found and removed

Since: 3.6

### e_source_refresh_remove_timeouts_by_data ()

    guint
    e_source_refresh_remove_timeouts_by_data
                                   (ESource *source,
                                    gpointer user_data);

Removes all timeout GSource's added by `e_source_refresh_add_timeout()` whose callback data pointer matches `user_data` .

#### Parameters

source | an ESource |
user_data | user data to match against timeout callbacks |

#### Returns

the number of timeouts found and removed

Since: 3.6

## Types and Values

### E_SOURCE_EXTENSION_REFRESH

    #define E_SOURCE_EXTENSION_REFRESH "Refresh"

Pass this extension name to `e_source_get_extension()` to access ESourceRefresh. This is also used as a group name in key files.

Since: 3.6

### struct ESourceRefresh

    struct ESourceRefresh;

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

Since: 3.6