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 ()
gboolean | (*ECalRecurInstanceFn) ()
icaltimezone * | (*ECalRecurResolveTimezoneFn) ()
void | e_cal_recur_generate_instances ()
time_t | e_cal_recur_obtain_enddate ()
gboolean | e_cal_recur_ensure_end_dates ()
const gchar ** | e_cal_get_recur_nth ()
const gchar * | e_cal_recur_get_localized_nth ()
gchar * | e_cal_recur_describe_recurrence ()

## Types and Values

#define | e_cal_recur_nth
enum | ECalRecurDescribeRecurrenceFlags

## Description

## Functions

### ECalRecurResolveTimezoneCb ()

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

### ECalRecurInstanceCb ()

    gboolean
    (*ECalRecurInstanceCb) (icalcomponent *comp,
                            struct icaltimetype instance_start,
                            struct icaltimetype instance_end,
                            gpointer user_data,
                            GCancellable *cancellable,
                            GError **error);

### e_cal_recur_generate_instances_sync ()

    gboolean
    e_cal_recur_generate_instances_sync (icalcomponent *comp,
                                         struct icaltimetype interval_start,
                                         struct icaltimetype 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

comp | 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]
callback_user_data | user data for `callback` . | [closure callback]
get_tz_callback | a callback to call when resolving timezone. | [scope call]
get_tz_callback_user_data | user data for `get_tz_callback` . | [closure get_tz_callback]
default_timezone | a default icaltimezone |
cancellable | a GCancellable; can be `NULL` |
error | a GError to set an error, if any. | [out]

#### Returns

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

Since: 3.20

### ECalRecurInstanceFn ()

    gboolean
    (*ECalRecurInstanceFn) (ECalComponent *comp,
                            time_t instance_start,
                            time_t instance_end,
                            gpointer user_data);

### ECalRecurResolveTimezoneFn ()

    icaltimezone *
    (*ECalRecurResolveTimezoneFn) (const gchar *tzid,
                                   gpointer data);

### e_cal_recur_generate_instances ()

    void
    e_cal_recur_generate_instances (ECalComponent *comp,
                                    time_t start,
                                    time_t end,
                                    ECalRecurInstanceFn cb,
                                    gpointer cb_data,
                                    ECalRecurResolveTimezoneFn tz_cb,
                                    gpointer tz_cb_data,
                                    icaltimezone *default_timezone);

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.

Both start and end can be -1, in which case we start at the events first instance and continue until it ends, or forever if it has no enddate.

The tz_cb 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).

Note: This will be replaced by `e_cal_recur_generate_instances_sync()`.

#### Parameters

comp | A calendar component object |
start | Range start time |
end | Range end time |
cb | Callback function. | [closure cb_data][scope call]
cb_data | Closure data for the callback function. | [closure]
tz_cb | Callback for retrieving timezones. | [closure tz_cb_data][scope call]
tz_cb_data | Closure data for the timezone callback. | [closure]
default_timezone | Default timezone to use when a timezone cannot be found |

### e_cal_recur_obtain_enddate ()

    time_t
    e_cal_recur_obtain_enddate (struct icalrecurrencetype *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,
                                  ECalRecurResolveTimezoneFn tz_cb,
                                  gpointer tz_cb_data);

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 "X-EVOLUTION-ENDDATE" 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. | [closure tz_cb_data][scope call]
tz_cb_data | data to pass to `tz_cb` . | [closure]

#### Returns

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

Since: 2.32

### e_cal_get_recur_nth ()

    const gchar **
    e_cal_get_recur_nth (void);

`e_cal_get_recur_nth` has been deprecated since version 3.28 and should not be used in newly-written code.

Use `e_cal_recur_get_localized_nth()` instead

Returns an array of 31 translated strings for each day of the month (i.e. "1st", "2nd", and so on).

#### Returns

a pointer to an array of strings. This array is static, do not free it.

### e_cal_recur_get_localized_nth ()

    const gchar *
    e_cal_recur_get_localized_nth (gint nth);

`e_cal_recur_get_localized_nth` is deprecated and should not be used in newly-written code.

#### 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

### 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 output format and what to do when the `icalcomp` contain 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.

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_recur_nth

    #define e_cal_recur_nth (e_cal_get_recur_nth ())

`e_cal_recur_nth` has been deprecated since version 3.28 and should not be used in newly-written code.

Use `e_cal_recur_get_localized_nth()` instead

An array of 31 translated strings for each day of the month (i.e. "1st", "2nd", and so on).

### enum ECalRecurDescribeRecurrenceFlags

Influences behaviour of `e_cal_recur_describe_recurrence()`.

#### Members

E_CAL_RECUR_DESCRIBE_RECURRENCE_FLAG_NONE | no extra flags, either returns `NULL` or the recurrence description, something like "Every 2 weeks..." |
E_CAL_RECUR_DESCRIBE_RECURRENCE_FLAG_PREFIXED | either returns `NULL` or the recurrence description prefixed with text like "The meeting recurs", forming something like "The meeting recurs every 2 weeks..." |
E_CAL_RECUR_DESCRIBE_RECURRENCE_FLAG_FALLBACK | returns `NULL` only if the component doesn't recur, otherwise returns either the recurrence description or at least text like "The meeting recurs" |

Since: 3.30