EReminderWatcher: Evolution-Data-Server Reference Manual

## EReminderWatcher EReminderWatcher — Calendar reminder watcher |

## Functions

EReminderData * | e_reminder_data_new ()
EReminderData * | e_reminder_data_copy ()
void | e_reminder_data_free ()
const gchar * | e_reminder_data_get_source_uid ()
void | e_reminder_data_set_source_uid ()
ECalComponent * | e_reminder_data_get_component ()
void | e_reminder_data_set_component ()
ECalComponentAlarmInstance * | e_reminder_data_get_instance ()
void | e_reminder_data_set_instance ()
EReminderWatcher * | e_reminder_watcher_new ()
ESourceRegistry * | e_reminder_watcher_get_registry ()
ECalClient * | e_reminder_watcher_ref_opened_client ()
void | e_reminder_watcher_set_default_zone ()
ICalTimezone * | e_reminder_watcher_dup_default_zone ()
gboolean | e_reminder_watcher_get_timers_enabled ()
void | e_reminder_watcher_set_timers_enabled ()
gchar * | e_reminder_watcher_describe_data ()
void | e_reminder_watcher_timer_elapsed ()
GSList * | e_reminder_watcher_dup_past ()
GSList * | e_reminder_watcher_dup_snoozed ()
void | e_reminder_watcher_snooze ()
void | e_reminder_watcher_dismiss ()
gboolean | e_reminder_watcher_dismiss_finish ()
gboolean | e_reminder_watcher_dismiss_sync ()
void | e_reminder_watcher_dismiss_all ()
gboolean | e_reminder_watcher_dismiss_all_finish ()
gboolean | e_reminder_watcher_dismiss_all_sync ()

## Types and Values

#define | E_TYPE_REMINDER_WATCHER_ZONE
enum | EReminderWatcherDescribeFlags
struct | EReminderWatcher
| EReminderData

## 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][nullable]

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][type EReminderData]

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