Libical API Documentation  3.0
Typedefs | Functions
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)
 Return an integer matrix of total events per delta_t timespan. More...
 
icalcomponenticalspanlist_as_vfreebusy (icalspanlist *sl, const char *organizer, const char *attendee)
 Return a valid VFREEBUSY component for this span. More...
 
void icalspanlist_dump (icalspanlist *s)
 (Debug) print out spanlist to stdout. More...
 
void icalspanlist_free (icalspanlist *spl)
 Destructor. More...
 
icalspanlisticalspanlist_from_vfreebusy (icalcomponent *comp)
 Construct an icalspanlist from a VFREEBUSY component. More...
 
icalspanlisticalspanlist_new (icalset *set, struct icaltimetype start, struct icaltimetype end)
 Constructor Make a free list from a set of component. Start and end should be in UTC. More...
 
struct icalperiodtype icalspanlist_next_free_time (icalspanlist *sl, struct icaltimetype t)
 Find next free time span in a spanlist. More...
 

Detailed Description

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

Function Documentation

◆ icalspanlist_as_freebusy_matrix()

int* icalspanlist_as_freebusy_matrix ( icalspanlist sl,
int  delta_t 
)

Return an integer matrix of total events per delta_t timespan.

Return an integer matrix of total events per delta_t timespan.

Parameters
slA valid icalspanlist
delta_tThe 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.

calculate the start and end time as time_t


insure that the time period falls on a time boundary divisable by delta_t

find the duration of this spanlist
malloc our matrix, add one extra slot for a final -1

◆ icalspanlist_as_vfreebusy()

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

Return a valid VFREEBUSY component for this span.

Return a valid VFREEBUSY component for this span.

Parameters
slA valid icalspanlist, from icalspanlist_new()
organizerThe organizer specified as "MAILTO:user@domain"
attendeeThe 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
slA valid icalspanlist.

◆ icalspanlist_free()

void icalspanlist_free ( icalspanlist s)

Destructor.

Parameters
sA valid icalspanlist

Free memory associated with the spanlist

◆ icalspanlist_from_vfreebusy()

icalspanlist* icalspanlist_from_vfreebusy ( icalcomponent comp)

Construct an icalspanlist from a VFREEBUSY component.

Construct an icalspanlist from a VFREEBUSY component.

Parameters
compA 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 
)

Constructor Make a free list from a set of component. Start and end should be in UTC.

Constructor Make a free list from a set of component. Start and end should be in UTC.

Parameters
setA valid icalset containing VEVENTS
startThe free list starts at this date/time
endThe 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.

◆ icalspanlist_next_free_time()

struct icalperiodtype icalspanlist_next_free_time ( icalspanlist sl,
struct icaltimetype  t 
)

Find next free time span in a spanlist.

Get first next free time after time t. all times are in UTC.

Parameters
slThe spanlist to search.
tThe time to start looking.

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