e-cal-recur: Evolution-Data-Server Reference Manual

## e-cal-recur e-cal-recur |

## Functions

ICalTimezone * | (*ECalRecurResolveTimezoneCb) ()
gboolean | (*ECalRecurInstanceCb) ()
gboolean | e_cal_recur_generate_instances_sync ()
time_t | e_cal_recur_obtain_enddate ()
gboolean | e_cal_recur_ensure_end_dates ()
const gchar * | e_cal_recur_get_localized_nth ()
void | (*ECalRecurFormatDateTimeFunc) ()
gchar * | e_cal_recur_describe_recurrence_ex ()
gchar * | e_cal_recur_describe_recurrence ()

## Types and Values

#define | E_CAL_EVOLUTION_ENDDATE_PARAMETER

## Description

## Functions

### ECalRecurResolveTimezoneCb ()

    ICalTimezone *
    (*ECalRecurResolveTimezoneCb) (const gchar *tzid,
                                   gpointer user_data,
                                   GCancellable *cancellable,
                                   GError **error);

Resolve timezone by its ID provided as `tzid` . The returned object, if not `NULL`, is owned by the callback implementation and should not be freed.

#### Parameters

tzid | timezone ID to resolve |
user_data | user data used for this callback |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

an ICalTimezone object for `tzid` , or `NULL`, on error or if not found.

[transfer none][nullable]

Since: 3.34

### ECalRecurInstanceCb ()

    gboolean
    (*ECalRecurInstanceCb) (ICalComponent *icomp,
                            ICalTime *instance_start,
                            ICalTime *instance_end,
                            gpointer user_data,
                            GCancellable *cancellable,
                            GError **error);

Callback used by `e_cal_recur_generate_instances_sync()`, called for each instance of a (recurring) component within given time range.

#### Parameters

icomp | an ICalComponent |
instance_start | start time of an instance |
instance_end | end time of an instance |
user_data | user data used for this callback in `e_cal_recur_generate_instances_sync()` |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE`, to continue recurrence generation, `FALSE` to stop

Since: 3.34

### e_cal_recur_generate_instances_sync ()

    gboolean
    e_cal_recur_generate_instances_sync (ICalComponent *icalcomp,
                                         ICalTime *interval_start,
                                         ICalTime *interval_end,
                                         ECalRecurInstanceCb callback,
                                         gpointer callback_user_data,
                                         ECalRecurResolveTimezoneCb get_tz_callback,
                                         gpointer get_tz_callback_user_data,
                                         ICalTimezone *default_timezone,
                                         GCancellable *cancellable,
                                         GError **error);

Calls the given callback function for each occurrence of the event that intersects the range between the given `start` and `end` times (the end time is not included). Note that the occurrences may start before the given start time.

If the callback routine returns FALSE the occurrence generation stops.

The start and end times are required valid times, start before end time.

The `get_tz_callback` is used to resolve references to timezones. It is passed a TZID and should return the ICalTimezone * corresponding to that TZID. We need to do this as we access timezones in different ways on the client & server.

The default_timezone argument is used for DTSTART or DTEND properties that are DATE values or do not have a TZID (i.e. floating times).

#### Parameters

icalcomp | an ICalComponent |
interval_start | an interval start, for which generate instances |
interval_end | an interval end, for which generate instances |
callback | a callback to be called for each instance. | [scope call][closure callback_user_data]
callback_user_data | user data for `callback` |
get_tz_callback | a callback to call when resolving timezone. | [scope call][closure get_tz_callback_user_data]
get_tz_callback_user_data | user data for `get_tz_callback` |
default_timezone | a default ICalTimezone |
cancellable | a GCancellable; can be `NULL` |
error | a GError to set an error, if any |

#### Returns

`TRUE` if successful (when all instances had been returned), `FALSE` otherwise.

Since: 3.20

### e_cal_recur_obtain_enddate ()

    time_t
    e_cal_recur_obtain_enddate (ICalRecurrence *ir,
                                ICalProperty *prop,
                                ICalTimezone *zone,
                                gboolean convert_end_date);

### e_cal_recur_ensure_end_dates ()

    gboolean
    e_cal_recur_ensure_end_dates (ECalComponent *comp,
                                  gboolean refresh,
                                  ECalRecurResolveTimezoneCb tz_cb,
                                  gpointer tz_cb_data,
                                  GCancellable *cancellable,
                                  GError **error);

This recalculates the end dates for recurrence & exception rules which use the COUNT property. If `refresh` is `TRUE` it will recalculate all enddates for rules which use COUNT. If `refresh` is `FALSE`, it will only calculate the enddate if it hasn't already been set. It returns `TRUE` if the component was changed, i.e. if the component should be saved at some point. We store the enddate in the `E_CAL_EVOLUTION_ENDDATE_PARAMETER` parameter of the RRULE or EXRULE.

#### Parameters

comp | an ECalComponent |
refresh | `TRUE` to recalculate all end dates |
tz_cb | function to call to resolve timezones. | [scope call][closure tz_cb_data]
tz_cb_data | user data to pass to `tz_cb` |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the component was changed, `FALSE` otherwise

Since: 2.32

### e_cal_recur_get_localized_nth ()

    const gchar *
    e_cal_recur_get_localized_nth (gint nth);

#### Parameters

nth | the nth index, counting from zero |

#### Returns

Localized text for the nth position, counting from zero, which means for '0' it'll return "1st", for '1' it'll return "2nd" and so on, up to 30, when it'll return "31st".

Since: 3.28

### ECalRecurFormatDateTimeFunc ()

    void
    (*ECalRecurFormatDateTimeFunc) (ICalTime *itt,
                                    gchar *buffer,
                                    gint buffer_size);

Format the date/time value from `itt` into `buffer` , whose size cannot exceed `buffer_size` letters.

#### Parameters

itt | an ICalTime to format to string |
buffer | a buffer to fill with the result |
buffer_size | the `buffer` size, in bytes, not counting the NUL-terminator character |

Since: 3.38

### e_cal_recur_describe_recurrence_ex ()

    gchar *
    e_cal_recur_describe_recurrence_ex (ICalComponent *icalcomp,
                                        GDateWeekday week_start_day,
                                        guint32 flags,
                                        ECalRecurFormatDateTimeFunc datetime_fmt_func);

Describes some simple types of recurrences in a human-readable and localized way. The `flags` influence the output format and what to do when the `icalcomp` contains more complicated recurrence, some which the function cannot describe.

The `week_start_day` is used for weekly recurrences, to start the list of selected days at that day.

If `datetime_fmt_func` is `NULL`, the `e_time_format_date_and_time()` is used to format data/time value.

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

#### Parameters

icalcomp | an ICalComponent |
week_start_day | a day when the week starts |
flags | bit-or of ECalRecurDescribeRecurrenceFlags |
datetime_fmt_func | formatting function for date/time value. | [nullable][scope call]

#### Returns

a newly allocated string, which describes the recurrence of the `icalcomp` , or NULL, when the `icalcomp` doesn't recur or the recurrence is too complicated to describe, also according to given `flags` .

[nullable][transfer full]

Since: 3.38

### e_cal_recur_describe_recurrence ()

    gchar *
    e_cal_recur_describe_recurrence (ICalComponent *icalcomp,
                                     GDateWeekday week_start_day,
                                     guint32 flags);

Describes some simple types of recurrences in a human-readable and localized way. The `flags` influence the output format and what to do when the `icalcomp` contains more complicated recurrence, some which the function cannot describe.

The `week_start_day` is used for weekly recurrences, to start the list of selected days at that day.

Uses `e_time_format_date_and_time()` to format the date/time value in the string. Call `e_cal_recur_describe_recurrence_ex()` with a custom formatting function.

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

#### Parameters

icalcomp | an ICalComponent |
week_start_day | a day when the week starts |
flags | bit-or of ECalRecurDescribeRecurrenceFlags |

#### Returns

a newly allocated string, which describes the recurrence of the `icalcomp` , or NULL, when the `icalcomp` doesn't recur or the recurrence is too complicated to describe, also according to given `flags` .

[nullable][transfer full]

Since: 3.30

## Types and Values

### E_CAL_EVOLUTION_ENDDATE_PARAMETER

    #define E_CAL_EVOLUTION_ENDDATE_PARAMETER "X-EVOLUTION-ENDDATE"

The X parameter name being used to store the enddate in RRULE and EXRULE properties.

Since: 3.34