EReminderWatcher

EReminderWatcher — Calendar reminder watcher

Functions

Types and Values

Object Hierarchy

    GBoxed
    ╰── EReminderData
    GObject
    ╰── EReminderWatcher

Includes

#include <libecal/libecal.h>

Description

The EReminderWatcher watches reminders in configured calendars and notifies the owner about them through signals. It also remembers past and snoozed reminders. It doesn't provide any GUI, it's all up to the owner to provide such functionality.

The API is thread safe and each signal is emitted from the thread of the default main context of the process.

Functions

e_reminder_data_new ()

EReminderData *
e_reminder_data_new (const gchar *source_uid,
                     const ECalComponent *component,
                     const ECalComponentAlarmInstance *instance);

Parameters

source_uid

an ESource UID, to which the component belongs

 

component

an ECalComponent

 

instance

an ECalComponentAlarmInstance describing one reminder instance

 

Returns

a new EReminderData prefilled with given values. Free the returned structure with e_reminder_data_free() when no longer needed.

[transfer full]

Since: 3.30


e_reminder_data_copy ()

EReminderData *
e_reminder_data_copy (const EReminderData *rd);

Copies given EReminderData structure. When the rd is NULL, simply returns NULL as well.

Parameters

rd

source EReminderData, or NULL.

[nullable]

Returns

copy of rd . Free the returned structure with e_reminder_data_free() when no longer needed.

[transfer full]

Since: 3.30


e_reminder_data_free ()

void
e_reminder_data_free (gpointer rd);

Frees previously allocated EReminderData structure with e_reminder_data_new() or e_reminder_data_copy(). The function does nothing when rd is NULL.

Parameters

rd

an EReminderData, or NULL.

[nullable]

Since: 3.30


e_reminder_data_get_source_uid ()

const gchar *
e_reminder_data_get_source_uid (const EReminderData *rd);

Parameters

rd

an EReminderData

 

Returns

an ESource UID for rd

Since: 3.34


e_reminder_data_set_source_uid ()

void
e_reminder_data_set_source_uid (EReminderData *rd,
                                const gchar *source_uid);

Set an ESource UID for rd .

Parameters

rd

an EReminderData

 

source_uid

an ESource UID

 

Since: 3.34


e_reminder_data_get_component ()

ECalComponent *
e_reminder_data_get_component (const EReminderData *rd);

Parameters

rd

an EReminderData

 

Returns

an ECalComponent for rd . It is owned by rd , thus do not free it.

[transfer none]

Since: 3.34


e_reminder_data_set_component ()

void
e_reminder_data_set_component (EReminderData *rd,
                               const ECalComponent *component);

Set an ECalComponent component as associated with this rd . The rd creates a copy of the component .

Parameters

rd

an EReminderData

 

component

an ECalComponent

 

Since: 3.34


e_reminder_data_get_instance ()

ECalComponentAlarmInstance *
e_reminder_data_get_instance (const EReminderData *rd);

Parameters

rd

an EReminderData

 

Returns

an ECalComponentAlarmInstance for rd . It is owned by rd , thus do not free it.

[transfer none]

Since: 3.34


e_reminder_data_set_instance ()

void
e_reminder_data_set_instance (EReminderData *rd,
                              const ECalComponentAlarmInstance *instance);

Set an ECalComponentAlarmInstance instance as associated with this rd . The rd creates a copy of the instance .

Parameters

rd

an EReminderData

 

instance

an ECalComponentAlarmInstance

 

Since: 3.34


e_reminder_watcher_new ()

EReminderWatcher *
e_reminder_watcher_new (ESourceRegistry *registry);

Creates a new EReminderWatcher, which will use the registry . It adds its own reference to registry . Free the created EReminderWatcher with g_object_unref() when no longer needed.

Parameters

registry

an ESourceRegistry.

[transfer none]

Returns

a new instance of EReminderWatcher.

[transfer full]

Since: 3.30


e_reminder_watcher_get_registry ()

ESourceRegistry *
e_reminder_watcher_get_registry (EReminderWatcher *watcher);

Parameters

watcher

an EReminderWatcher

 

Returns

an ESourceRegistry with which the watcher had been created.

[transfer none]


e_reminder_watcher_ref_opened_client ()

ECalClient *
e_reminder_watcher_ref_opened_client (EReminderWatcher *watcher,
                                      const gchar *source_uid);

Parameters

watcher

an EReminderWatcher

 

source_uid

an ESource UID of the calendar to return

 

Returns

a referenced ECalClient for the source_uid , if any such is opened; NULL otherwise.

[transfer full][nullable]

Since: 3.30


e_reminder_watcher_set_default_zone ()

void
e_reminder_watcher_set_default_zone (EReminderWatcher *watcher,
                                     const ICalTimezone *zone);

Sets the default zone for the watcher . This is used when calculating trigger times for floating component times. When the zone is NULL, then sets a UTC time zone.

Parameters

watcher

an EReminderWatcher

 

zone

an ICalTimezone.

[nullable]

Since: 3.30


e_reminder_watcher_dup_default_zone ()

ICalTimezone *
e_reminder_watcher_dup_default_zone (EReminderWatcher *watcher);

Parameters

watcher

an EReminderWatcher

 

Returns

A copy of the currently set default time zone. Free it with g_object_unref(), when no longer needed.

[transfer full]

Since: 3.30


e_reminder_watcher_get_timers_enabled ()

gboolean
e_reminder_watcher_get_timers_enabled (EReminderWatcher *watcher);

Parameters

watcher

an EReminderWatcher

 

Returns

whether timers are enabled for the watcher . See e_reminder_watcher_set_timers_enabled() for more information what it means.

Since: 3.30


e_reminder_watcher_set_timers_enabled ()

void
e_reminder_watcher_set_timers_enabled (EReminderWatcher *watcher,
                                       gboolean enabled);

The watcher can be used both for scheduling the timers for the reminders and respond to them through the "triggered" signal, or only to listen for changes on the past reminders. The default is to have timers enabled, thus to response to scheduled reminders. Disabling the timers also means there will be less resources needed by the watcher .

Parameters

watcher

an EReminderWatcher

 

enabled

a value to set

 

Since: 3.30


e_reminder_watcher_describe_data ()

gchar *
e_reminder_watcher_describe_data (EReminderWatcher *watcher,
                                  const EReminderData *rd,
                                  guint32 flags);

Returns a new string with a text description of the rd . The text format can be influenced with flags .

Free the returned string with g_free(), when no longer needed.

Parameters

watcher

an EReminderWatcher

 

rd

an EReminderData

 

flags

bit-or of EReminderWatcherDescribeFlags

 

Returns

a new string with a text description of the rd .

[transfer full]

Since: 3.30


e_reminder_watcher_timer_elapsed ()

void
e_reminder_watcher_timer_elapsed (EReminderWatcher *watcher);

Notifies the watcher that the timer previously scheduled with EReminderWatcherClass::schedule_timer elapsed. This can be used by the descendants which override the default implementation of EReminderWatcherClass::schedule_timer. There is always scheduled only one timer and once it's elapsed it should be also removed, the same when the EReminderWatcherClass::schedule_timer is called and the previously scheduled timer was not elapsed yet, the previous should be removed first, aka every call to EReminderWatcherClass::schedule_timer replaces any previously scheduled timer.

Parameters

watcher

an EReminderWatcher

 

Since: 3.30


e_reminder_watcher_dup_past ()

GSList *
e_reminder_watcher_dup_past (EReminderWatcher *watcher);

Gathers a GSList of all past reminders which had not been removed after EReminderWatcher::triggered signal. Such reminders are remembered across sessions, until they are dismissed by e_reminder_watcher_dismiss() or its synchronous variant. These reminders can be also snoozed with e_reminder_watcher_snooze(), which removes them from the past reminders into the list of snoozed reminders, see e_reminder_watcher_dup_snoozed().

Free the returned GSList with g_slist_free_full (reminders, e_reminder_data_free); when no longer needed.

Parameters

watcher

an EReminderWatcher

 

Returns

a newly allocated GSList of the past reminders, or NULL, when there are none.

[transfer full][element-type EReminderData][nullable]

Since: 3.30


e_reminder_watcher_dup_snoozed ()

GSList *
e_reminder_watcher_dup_snoozed (EReminderWatcher *watcher);

Gathers a GSList of currently snoozed reminder with e_reminder_watcher_snooze(). The snoozed reminders are remembered across sessions and they are re-triggered when their snooze time elapses, which can move them back to the list of past reminders.

Free the returned GSList with g_slist_free_full (reminders, e_reminder_data_free); when no longer needed.

Parameters

watcher

an EReminderWatcher

 

Returns

a newly allocated GSList of the snoozed reminders, or NULL, when there are none.

[transfer full][element-type EReminderData][nullable]

Since: 3.30


e_reminder_watcher_snooze ()

void
e_reminder_watcher_snooze (EReminderWatcher *watcher,
                           const EReminderData *rd,
                           gint64 until);

Snoozes rd until until , which is an absolute time when the rd should be retriggered. This moves the rd from the list of past reminders into the list of snoozed reminders and invokes the "changed" signal.

The until can be a special value 0, to set the time as the event start, if it's in the future. The function does nothing when the event time is in the past.

Parameters

watcher

an EReminderWatcher

 

rd

an EReminderData identifying the reminder

 

until

time_t as gint64, when the rd should be retriggered

 

Since: 3.30


e_reminder_watcher_dismiss ()

void
e_reminder_watcher_dismiss (EReminderWatcher *watcher,
                            const EReminderData *rd,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Asynchronously dismiss single reminder in the past or snoozed reminders.

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

Parameters

watcher

an EReminderWatcher

 

rd

an EReminderData to dismiss

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since: 3.30


e_reminder_watcher_dismiss_finish ()

gboolean
e_reminder_watcher_dismiss_finish (EReminderWatcher *watcher,
                                   GAsyncResult *result,
                                   GError **error);

Finishes the operation started with e_reminder_watcher_dismiss().

Parameters

watcher

an EReminderWatcher

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.30


e_reminder_watcher_dismiss_sync ()

gboolean
e_reminder_watcher_dismiss_sync (EReminderWatcher *watcher,
                                 const EReminderData *rd,
                                 GCancellable *cancellable,
                                 GError **error);

Synchronously dismiss single reminder in the past or snoozed reminders.

Parameters

watcher

an EReminderWatcher

 

rd

an EReminderData to dismiss

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.30


e_reminder_watcher_dismiss_all ()

void
e_reminder_watcher_dismiss_all (EReminderWatcher *watcher,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronously dismiss all past reminders.

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

Parameters

watcher

an EReminderWatcher

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since: 3.30


e_reminder_watcher_dismiss_all_finish ()

gboolean
e_reminder_watcher_dismiss_all_finish (EReminderWatcher *watcher,
                                       GAsyncResult *result,
                                       GError **error);

Finishes the operation started with e_reminder_watcher_dismiss_all().

Parameters

watcher

an EReminderWatcher

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.30


e_reminder_watcher_dismiss_all_sync ()

gboolean
e_reminder_watcher_dismiss_all_sync (EReminderWatcher *watcher,
                                     GCancellable *cancellable,
                                     GError **error);

Synchronously dismiss all past reminders. The operation stops after the first error is encountered, which can be before all the past reminders are dismissed.

Parameters

watcher

an EReminderWatcher

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

whether succeeded.

Since: 3.30

Types and Values

E_TYPE_REMINDER_WATCHER_ZONE

#define E_TYPE_REMINDER_WATCHER_ZONE (e_reminder_watcher_zone_get_type ())

enum EReminderWatcherDescribeFlags

Flags modifying behaviour of e_reminder_watcher_describe_data().

Members

E_REMINDER_WATCHER_DESCRIBE_FLAG_NONE

None flags

 

E_REMINDER_WATCHER_DESCRIBE_FLAG_MARKUP

Returned description will contain also markup. Without it it'll be a plain text.

 

Since: 3.30


struct EReminderWatcher

struct EReminderWatcher;

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

Since: 3.30


EReminderData

typedef struct _EReminderData EReminderData;

Contains data related to single reminder occurrence.

Members

Since: 3.30