ESourceRefresh

ESourceRefresh — ESource extension for refresh settings

Synopsis

#include <libedataserver/libedataserver.h>

struct              ESourceRefresh;
#define             E_SOURCE_EXTENSION_REFRESH
gboolean            e_source_refresh_get_enabled        (ESourceRefresh *extension);
void                e_source_refresh_set_enabled        (ESourceRefresh *extension,
                                                         gboolean enabled);
guint               e_source_refresh_get_interval_minutes
                                                        (ESourceRefresh *extension);
void                e_source_refresh_set_interval_minutes
                                                        (ESourceRefresh *extension,
                                                         guint interval_minutes);
void                (*ESourceRefreshFunc)               (ESource *source,
                                                         gpointer user_data);
guint               e_source_refresh_add_timeout        (ESource *source,
                                                         GMainContext *context,
                                                         ESourceRefreshFunc callback,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
void                e_source_refresh_force_timeout      (ESource *source);
gboolean            e_source_refresh_remove_timeout     (ESource *source,
                                                         guint refresh_timeout_id);
guint               e_source_refresh_remove_timeouts_by_data
                                                        (ESource *source,
                                                         gpointer user_data);

Object Hierarchy

  GObject
   +----ESourceExtension
         +----ESourceRefresh

Properties

  "enabled"                  gboolean              : Read / Write / Construct
  "interval-minutes"         guint                 : Read / Write / Construct

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);

Details

struct ESourceRefresh

struct ESourceRefresh;

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

Since 3.6


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


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.

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.

extension :

an ESourceRefresh

enabled :

whether to enable periodic refresh

Since 3.6


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.

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.

extension :

an ESourceRefresh

interval_minutes :

the interval in minutes

Since 3.6


ESourceRefreshFunc ()

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

source :

an ESource

user_data :

user data provided to the callback function

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

source :

an ESource

context :

a GMainContext, or NULL (if NULL, the default context will be used). [allow-none]

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

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.

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

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.

source :

an ESource

user_data :

user data to match against timeout callbacks

Returns :

the number of timeouts found and removed

Since 3.6

Property Details

The "enabled" property

  "enabled"                  gboolean              : Read / Write / Construct

Whether to periodically refresh.

Default value: TRUE


The "interval-minutes" property

  "interval-minutes"         guint                 : Read / Write / Construct

Refresh interval in minutes.

Default value: 60