icalrecur.h File Reference

Routines for dealing with recurring time. More...

Go to the source code of this file.

Data Structures
struct	icalrecurrencetype

Macros
#define	ICAL_BY_DAY_SIZE   7*(ICAL_BY_WEEKNO_SIZE-1)+1 /* 1 to N */
#define	ICAL_BY_HOUR_SIZE   25 /* 0 to 23 */
#define	ICAL_BY_MINUTE_SIZE   61 /* 0 to 59 */
#define	ICAL_BY_MONTH_SIZE   14 /* 1 to 13 */
#define	ICAL_BY_MONTHDAY_SIZE   32 /* 1 to 31 */
#define	ICAL_BY_SECOND_SIZE   62 /* 0 to 60 */
#define	ICAL_BY_SETPOS_SIZE   ICAL_BY_YEARDAY_SIZE /* 1 to N */
#define	ICAL_BY_WEEKNO_SIZE   56 /* 1 to 55 */
#define	ICAL_BY_YEARDAY_SIZE   386 /* 1 to 385 */
#define	ICALRECURRENCETYPE_INITIALIZER

Typedefs
typedef struct icalrecur_iterator_impl	icalrecur_iterator
typedef enum icalrecurrencetype_frequency	icalrecurrencetype_frequency
typedef enum icalrecurrencetype_skip	icalrecurrencetype_skip
typedef enum icalrecurrencetype_weekday	icalrecurrencetype_weekday

Enumerations
enum	icalrecurrence_array_max_values { ICAL_RECURRENCE_ARRAY_MAX = 0x7f7f , ICAL_RECURRENCE_ARRAY_MAX_BYTE = 0x7f }
enum	icalrecurrencetype_frequency {   ICAL_SECONDLY_RECURRENCE = 0 , ICAL_MINUTELY_RECURRENCE = 1 , ICAL_HOURLY_RECURRENCE = 2 , ICAL_DAILY_RECURRENCE = 3 ,   ICAL_WEEKLY_RECURRENCE = 4 , ICAL_MONTHLY_RECURRENCE = 5 , ICAL_YEARLY_RECURRENCE = 6 , ICAL_NO_RECURRENCE = 7 }
enum	icalrecurrencetype_skip { ICAL_SKIP_BACKWARD = 0 , ICAL_SKIP_FORWARD , ICAL_SKIP_OMIT , ICAL_SKIP_UNDEFINED }
enum	icalrecurrencetype_weekday {   ICAL_NO_WEEKDAY , ICAL_SUNDAY_WEEKDAY , ICAL_MONDAY_WEEKDAY , ICAL_TUESDAY_WEEKDAY ,   ICAL_WEDNESDAY_WEEKDAY , ICAL_THURSDAY_WEEKDAY , ICAL_FRIDAY_WEEKDAY , ICAL_SATURDAY_WEEKDAY }

Functions
int	icalrecur_expand_recurrence (const char *rule, time_t start, int count, time_t *array)
	Fills an array with the 'count' number of occurrences generated by the rrule.
const char *	icalrecur_freq_to_string (icalrecurrencetype_frequency kind)
void	icalrecur_iterator_free (icalrecur_iterator *)
icalrecur_iterator *	icalrecur_iterator_new (struct icalrecurrencetype rule, struct icaltimetype dtstart)
struct icaltimetype	icalrecur_iterator_next (icalrecur_iterator *)
int	icalrecur_iterator_set_start (icalrecur_iterator *impl, struct icaltimetype start)
const char *	icalrecur_skip_to_string (icalrecurrencetype_skip kind)
icalrecurrencetype_frequency	icalrecur_string_to_freq (const char *str)
icalrecurrencetype_skip	icalrecur_string_to_skip (const char *str)
icalrecurrencetype_weekday	icalrecur_string_to_weekday (const char *str)
const char *	icalrecur_weekday_to_string (icalrecurrencetype_weekday kind)
char *	icalrecurrencetype_as_string (struct icalrecurrencetype *recur)
char *	icalrecurrencetype_as_string_r (struct icalrecurrencetype *recur)
void	icalrecurrencetype_clear (struct icalrecurrencetype *r)
enum icalrecurrencetype_weekday	icalrecurrencetype_day_day_of_week (short day)
	Decodes a day to a weekday.
int	icalrecurrencetype_day_position (short day)
	Decodes a day to a position of the weekday.
struct icalrecurrencetype	icalrecurrencetype_from_string (const char *str)
int	icalrecurrencetype_month_is_leap (short month)
int	icalrecurrencetype_month_month (short month)
int	icalrecurrencetype_rscale_is_supported (void)
icalarray *	icalrecurrencetype_rscale_supported_calendars (void)

Detailed Description

Routines for dealing with recurring time.

How to use:

1) Get a rule and a start time from a component

icalproperty rrule;
struct icalrecurrencetype recur;
struct icaltimetype dtstart;
 
rrule = icalcomponent_get_first_property(comp,ICAL_RRULE_PROPERTY);
recur = icalproperty_get_rrule(rrule);
start = icalproperty_get_dtstart(dtstart);

Or, just make them up:

recur = icalrecurrencetype_from_string("FREQ=YEARLY;BYDAY=SU,WE");
dtstart = icaltime_from_string("19970101T123000")

2) Create an iterator

icalrecur_iterator *ritr;
ritr = icalrecur_iterator_new(recur,start);

3) Iterator over the occurrences

struct icaltimetype next;
while (next = icalrecur_iterator_next(ritr)
       && !icaltime_is_null_time(next){
        Do something with next
}

Note that the time returned by icalrecur_iterator_next is in whatever timezone that dtstart is in.

Macro Definition Documentation

ICAL_BY_SECOND_SIZE

#define ICAL_BY_SECOND_SIZE   62 /* 0 to 60 */

Recurrence type routines

ICALRECURRENCETYPE_INITIALIZER

#define ICALRECURRENCETYPE_INITIALIZER

Value:

    {                    \
    ICAL_NO_RECURRENCE,                  /* freq         */ \
    ICALTIMETYPE_INITIALIZER,            /* until        */ \
    0,                                   /* count        */ \
    1,                                   /* interval     */ \
    ICAL_MONDAY_WEEKDAY,                 /* week_start   */ \
    { ICAL_RECURRENCE_ARRAY_MAX_BYTE },  /* by_second    */ \
    { ICAL_RECURRENCE_ARRAY_MAX_BYTE },  /* by_minute    */ \
    { ICAL_RECURRENCE_ARRAY_MAX_BYTE },  /* by_hour      */ \
    { ICAL_RECURRENCE_ARRAY_MAX_BYTE },  /* by_day       */ \
    { ICAL_RECURRENCE_ARRAY_MAX_BYTE },  /* by_month_day */ \
    { ICAL_RECURRENCE_ARRAY_MAX_BYTE },  /* by_year_day  */ \
    { ICAL_RECURRENCE_ARRAY_MAX_BYTE },  /* by_week_no   */ \
    { ICAL_RECURRENCE_ARRAY_MAX_BYTE },  /* by_month     */ \
    { ICAL_RECURRENCE_ARRAY_MAX_BYTE },  /* by_set_pos   */ \
    NULL,                                /* rscale       */ \
    ICAL_SKIP_OMIT                       /* skip         */ \
}

Function Documentation

icalrecur_expand_recurrence()

int icalrecur_expand_recurrence	(	const char *	rule,
		time_t	start,
		int	count,
		time_t *	array
	)

Fills an array with the 'count' number of occurrences generated by the rrule.

Specifically, this fills array up with at most 'count' time_t values, each representing an occurrence time in seconds past the POSIX epoch.

Note that the times are returned in UTC, but the times are calculated in local time. You will have to convert the results back into local time before using them.

icalrecur_iterator_free()

void icalrecur_iterator_free

(

icalrecur_iterator *

i

)

Frees the iterator.

icalrecur_iterator_new()

icalrecur_iterator * icalrecur_iterator_new	(	struct icalrecurrencetype	rule,
		struct icaltimetype	dtstart
	)

Creates a new recurrence rule iterator, starting at DTSTART.

icalrecur_iterator_next()

struct icaltimetype icalrecur_iterator_next

(

icalrecur_iterator *

impl

)

Gets the next occurrence from an iterator.

icalrecur_iterator_set_start()

int icalrecur_iterator_set_start	(	icalrecur_iterator *	impl,
		struct icaltimetype	start
	)

Sets the date-time at which the iterator will start, where start is a value between DTSTART and UNTIL.

NOTE: CAN NOT be used with RRULEs that contain COUNT.

Since

3.0

icalrecurrencetype_day_day_of_week()

enum icalrecurrencetype_weekday icalrecurrencetype_day_day_of_week

(

short

day

)

Decodes a day to a weekday.

Returns

The decoded day of the week. 1 is Monday, 2 is Tuesday, etc. A position of 0 means 'any' or 'every'.

The 'day' element of icalrecurrencetype_weekday is encoded to allow representation of both the day of the week ( Monday, Tuesday), but also the Nth day of the week ( First tuesday of the month, last thursday of the year) These routines decode the day values.

The day's position in the period ( Nth-ness) and the numerical value of the day are encoded together as: pos*7 + dow.

icalrecurrencetype_day_position()

int icalrecurrencetype_day_position

(

short

day

)

Decodes a day to a position of the weekday.

Returns

The position of the day in the week. 0 == any of day of week. 1 == first, 2 = second, -2 == second to last, etc. 0 means 'any' or 'every'.

icalrecurrencetype_from_string()

struct icalrecurrencetype icalrecurrencetype_from_string

(

const char *

str

)

Convert between strings and recurrencetype structures.