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

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

Parameters

  sl | 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 * | s | ) |

(Debug) print out spanlist to STDOUT.

Parameters

  sl | A valid icalspanlist.

## ◆ icalspanlist_free()

void icalspanlist_free | ( | icalspanlist * | spl | ) |

Destructor.

Parameters

  s | 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.