icalspanlist.h File Reference

Code that supports collections of free/busy spans of time. More...

Go to the source code of this file.

Typedefs
typedef struct icalspanlist_impl	icalspanlist

Functions
int *	icalspanlist_as_freebusy_matrix (icalspanlist *span, int delta_t)
	Returns an hour-by-hour array of free/busy times over a given period.
icalcomponent *	icalspanlist_as_vfreebusy (icalspanlist *sl, const char *organizer, const char *attendee)
	Returns a VFREEBUSY component for a spanlist.
void	icalspanlist_dump (icalspanlist *sl)
	(Debug) print out spanlist to STDOUT.
void	icalspanlist_free (icalspanlist *sl)
	Destructor.
icalspanlist *	icalspanlist_from_vfreebusy (icalcomponent *comp)
	Constructs an icalspanlist from a VFREEBUSY component.
icalspanlist *	icalspanlist_new (icalset *set, struct icaltimetype start, struct icaltimetype end)
	Makes a free list from a set of VEVENT components.
struct icalperiodtype	icalspanlist_next_free_time (icalspanlist *sl, struct icaltimetype t)
	Finds the next free time span in a spanlist.

Detailed Description

Code that supports collections of free/busy spans of time.

Function Documentation

icalspanlist_as_freebusy_matrix()

int * icalspanlist_as_freebusy_matrix	(	icalspanlist *	span,
		int	delta_t )

Returns an hour-by-hour array of free/busy times over a given period.

Parameters

span	A valid icalspanlist
delta_t	The time slice to divide by, in seconds. Default 3600.

Returns

A pointer to an array of integers containing the number of busy events in each delta_t time period. The final entry contains the value -1.

This calculation is somewhat tricky. This is due to the fact that the time range contains the start time, but does not contain the end time. To perform a proper calculation we subtract one second off the end times to get a true containing time.

Also note that if you supplying a spanlist that does not start or end on a time boundary divisible by delta_t you may get results that are not quite what you expect.

icalspanlist_as_vfreebusy()

icalcomponent * icalspanlist_as_vfreebusy	(	icalspanlist *	sl,
		const char *	organizer,
		const char *	attendee )

Returns a VFREEBUSY component for a spanlist.

Parameters

sl	A valid icalspanlist, from icalspanlist_new()
organizer	The organizer specified as "MAILTO:user@domain"
attendee	The attendee specified as "MAILTO:user@domain"

Returns

A valid icalcomponent or NULL.

This function returns a VFREEBUSY component for the given spanlist. The start time is mapped to DTSTART, the end time to DTEND. Each busy span is represented as a separate FREEBUSY entry. An attendee parameter is required, and organizer parameter is optional.

icalspanlist_dump()

void icalspanlist_dump

(

icalspanlist *

sl

)

(Debug) print out spanlist to STDOUT.

Parameters

sl	A valid icalspanlist.

icalspanlist_free()

void icalspanlist_free

(

icalspanlist *

sl

)

Destructor.

Parameters

sl	A valid icalspanlist

Frees the memory associated with the spanlist.

icalspanlist_from_vfreebusy()

icalspanlist * icalspanlist_from_vfreebusy

(

icalcomponent *

comp

)

Constructs an icalspanlist from a VFREEBUSY component.

Constructs an icalspanlist from the VFREEBUSY component of an icalcomponent.

Parameters

comp	A valid icalcomponent.

Returns

A valid icalspanlist or NULL if no VFREEBUSY section.

icalspanlist_new()

icalspanlist * icalspanlist_new	(	icalset *	set,
		struct icaltimetype	start,
		struct icaltimetype	end )

Makes a free list from a set of VEVENT components.

Parameters

set	A valid icalset containing VEVENTS
start	The free list starts at this date/time
end	The free list ends at this date/time

Returns

A spanlist corresponding to the VEVENTS

Given a set of components, a start time and an end time return a spanlist that contains the free/busy times. Start and end should be in UTC.

icalspanlist_next_free_time()

struct icalperiodtype icalspanlist_next_free_time	(	icalspanlist *	sl,
		struct icaltimetype	t )

Finds the next free time span in a spanlist.

Parameters

sl	The spanlist to search.
t	The time to start looking.

Given a spanlist and a time, finds the next period of time that is free.