Libical API Documentation 3.0

Data Structures | Typedefs | Functions
icalcomponent.h File Reference

Go to the source code of this file.

## Data Structures
struct | icalcompiter

## Typedefs
typedef struct icalcompiter | icalcompiter
typedef struct icalcomponent_impl | icalcomponent

## Functions
icalcomponent * | icalcompiter_deref (icalcompiter *i)
icalcomponent * | icalcompiter_next (icalcompiter *i)
icalcomponent * | icalcompiter_prior (icalcompiter *i)
void | icalcomponent_add_component (icalcomponent *parent, icalcomponent *child)
void | icalcomponent_add_property (icalcomponent *component, icalproperty *property)
char * | icalcomponent_as_ical_string (icalcomponent *component)
char * | icalcomponent_as_ical_string_r (icalcomponent *component)
icalcompiter | icalcomponent_begin_component (icalcomponent *component, icalcomponent_kind kind)
int | icalcomponent_check_restrictions (icalcomponent *comp)
void | icalcomponent_convert_errors (icalcomponent *component)
| Converts some X-LIC-ERROR properties into RETURN-STATUS properties.
int | icalcomponent_count_components (icalcomponent *component, icalcomponent_kind kind)
int | icalcomponent_count_errors (icalcomponent *component)
| Returns the number of errors encountered parsing the data. More...
int | icalcomponent_count_properties (icalcomponent *component, icalproperty_kind kind)
icalcompiter | icalcomponent_end_component (icalcomponent *component, icalcomponent_kind kind)
void | icalcomponent_foreach_recurrence (icalcomponent *comp, struct icaltimetype start, struct icaltimetype end, void(*callback)(icalcomponent *comp, struct icaltime_span *span, void *data), void *callback_data)
| Cycles through all recurrences of an event. More...
void | icalcomponent_foreach_tzid (icalcomponent *comp, void(*callback)(icalparameter *param, void *data), void *callback_data)
| Calls the given function for each TZID parameter found in the component, and any subcomponents.
void | icalcomponent_free (icalcomponent *component)
const char * | icalcomponent_get_comment (icalcomponent *comp)
icalcomponent * | icalcomponent_get_current_component (icalcomponent *component)
icalproperty * | icalcomponent_get_current_property (icalcomponent *component)
const char * | icalcomponent_get_description (icalcomponent *comp)
struct icaltimetype | icalcomponent_get_dtend (icalcomponent *comp)
| Gets the DTEND property as an icaltime. More...
struct icaltimetype | icalcomponent_get_dtstamp (icalcomponent *comp)
struct icaltimetype | icalcomponent_get_dtstart (icalcomponent *comp)
| Gets the DTSTART property as an icaltime. More...
struct icaltimetype | icalcomponent_get_due (icalcomponent *comp)
| Returns the time a VTODO task is DUE. More...
struct icaldurationtype | icalcomponent_get_duration (icalcomponent *comp)
| Gets the DURATION property as an icalduration. More...
icalcomponent * | icalcomponent_get_first_component (icalcomponent *component, icalcomponent_kind kind)
icalproperty * | icalcomponent_get_first_property (icalcomponent *component, icalproperty_kind kind)
icalcomponent * | icalcomponent_get_first_real_component (icalcomponent *c)
| Returns a reference to the first VEVENT, VTODO or VJOURNAL in the component.
icalcomponent * | icalcomponent_get_inner (icalcomponent *comp)
const char * | icalcomponent_get_location (icalcomponent *comp)
icalproperty_method | icalcomponent_get_method (icalcomponent *comp)
| Returns the METHOD property.
icalcomponent * | icalcomponent_get_next_component (icalcomponent *component, icalcomponent_kind kind)
icalproperty * | icalcomponent_get_next_property (icalcomponent *component, icalproperty_kind kind)
icalcomponent * | icalcomponent_get_parent (icalcomponent *component)
struct icaltimetype | icalcomponent_get_recurrenceid (icalcomponent *comp)
const char * | icalcomponent_get_relcalid (icalcomponent *comp)
| Gets the RELCALID property of a component. More...
int | icalcomponent_get_sequence (icalcomponent *comp)
struct icaltime_span | icalcomponent_get_span (icalcomponent *comp)
| Gets the timespan covered by this component, in UTC. More...
enum icalproperty_status | icalcomponent_get_status (icalcomponent *comp)
const char * | icalcomponent_get_summary (icalcomponent *comp)
icaltimezone * | icalcomponent_get_timezone (icalcomponent *comp, const char *tzid)
| Returns the icaltimezone in the component corresponding to the TZID, or NULL if it can't be found.
const char * | icalcomponent_get_uid (icalcomponent *comp)
int | icalcomponent_is_valid (icalcomponent *component)
icalcomponent_kind | icalcomponent_isa (const icalcomponent *component)
int | icalcomponent_isa_component (void *component)
int | icalcomponent_kind_is_valid (const icalcomponent_kind kind)
const char * | icalcomponent_kind_to_string (icalcomponent_kind kind)
void | icalcomponent_merge_component (icalcomponent *comp, icalcomponent *comp_to_merge)
icalcomponent * | icalcomponent_new (icalcomponent_kind kind)
| Constructor.
icalcomponent * | icalcomponent_new_clone (icalcomponent *component)
| Constructor.
icalcomponent * | icalcomponent_new_from_string (const char *str)
| Constructor.
icalcomponent * | icalcomponent_new_vagenda (void)
icalcomponent * | icalcomponent_new_valarm (void)
icalcomponent * | icalcomponent_new_vavailability (void)
icalcomponent * | icalcomponent_new_vcalendar (void)
icalcomponent * | icalcomponent_new_vevent (void)
icalcomponent * | icalcomponent_new_vfreebusy (void)
icalcomponent * | icalcomponent_new_vjournal (void)
icalcomponent * | icalcomponent_new_vpatch (void)
icalcomponent * | icalcomponent_new_vpoll (void)
icalcomponent * | icalcomponent_new_vquery (void)
icalcomponent * | icalcomponent_new_vtimezone (void)
icalcomponent * | icalcomponent_new_vtodo (void)
icalcomponent * | icalcomponent_new_vvoter (void)
icalcomponent * | icalcomponent_new_x (const char *x_name)
| Constructor.
icalcomponent * | icalcomponent_new_xavailable (void)
icalcomponent * | icalcomponent_new_xdaylight (void)
icalcomponent * | icalcomponent_new_xpatch (void)
icalcomponent * | icalcomponent_new_xstandard (void)
icalcomponent * | icalcomponent_new_xvote (void)
void | icalcomponent_normalize (icalcomponent *comp)
| Normalizes (reorders and sorts the properties) the specified icalcomponent `comp`. More...
void | icalcomponent_remove_component (icalcomponent *parent, icalcomponent *child)
void | icalcomponent_remove_property (icalcomponent *component, icalproperty *property)
void | icalcomponent_set_comment (icalcomponent *comp, const char *v)
void | icalcomponent_set_description (icalcomponent *comp, const char *v)
void | icalcomponent_set_dtend (icalcomponent *comp, struct icaltimetype v)
| Sets the DTEND property to given icaltime. More...
void | icalcomponent_set_dtstamp (icalcomponent *comp, struct icaltimetype v)
void | icalcomponent_set_dtstart (icalcomponent *comp, struct icaltimetype v)
| Sets the DTSTART property to the given icaltime,. More...
void | icalcomponent_set_due (icalcomponent *comp, struct icaltimetype v)
| Sets the due date of a VTODO task. More...
void | icalcomponent_set_duration (icalcomponent *comp, struct icaldurationtype v)
| Sets the DURATION property to given icalduration. More...
void | icalcomponent_set_location (icalcomponent *comp, const char *v)
void | icalcomponent_set_method (icalcomponent *comp, icalproperty_method method)
| Sets the METHOD property to the given method.
void | icalcomponent_set_parent (icalcomponent *component, icalcomponent *parent)
void | icalcomponent_set_recurrenceid (icalcomponent *comp, struct icaltimetype v)
void | icalcomponent_set_relcalid (icalcomponent *comp, const char *v)
| Sets the RELCALID property of a component. More...
void | icalcomponent_set_sequence (icalcomponent *comp, int v)
void | icalcomponent_set_status (icalcomponent *comp, enum icalproperty_status v)
void | icalcomponent_set_summary (icalcomponent *comp, const char *v)
void | icalcomponent_set_uid (icalcomponent *comp, const char *v)
icalcomponent_kind | icalcomponent_string_to_kind (const char *string)
void | icalcomponent_strip_errors (icalcomponent *component)
| Removes all X-LIC-ERROR properties.
icalcomponent * | icalcomponent_vanew (icalcomponent_kind kind,...)
| Constructor.
struct icaltimetype | icalproperty_get_datetime_with_component (icalproperty *prop, icalcomponent *comp)
| Gets a DATE or DATE-TIME property as an icaltime. More...
icalcomponent * | icalproperty_get_parent (const icalproperty *property)
| Returns the parent icalcomponent for the specified `property`.
int | icalproperty_recurrence_is_excluded (icalcomponent *comp, struct icaltimetype *dtstart, struct icaltimetype *recurtime)
| Decides if a recurrence is acceptable. More...
void | icalproperty_set_parent (icalproperty *property, icalcomponent *component)
| Sets the parent icalcomponent for the specified icalproperty `property`. More...

## Function Documentation

## ◆ icalcomponent_count_errors()

int icalcomponent_count_errors | ( | icalcomponent * | component | ) |

Returns the number of errors encountered parsing the data.

This function counts the number times the X-LIC-ERROR occurs in the data structure.

## ◆ icalcomponent_foreach_recurrence()

void icalcomponent_foreach_recurrence | ( | icalcomponent * | comp,
|  | struct icaltimetype | start,
|  | struct icaltimetype | end,
|  | void(*)(icalcomponent *comp, struct icaltime_span *span, void *data) | callback,
|  | void * | callback_data
| ) |  |

Cycles through all recurrences of an event.

Parameters

  comp | A valid VEVENT component
  start | Ignore timespans before this
  end | Ignore timespans after this
  callback | Function called for each timespan within the range
  callback_data | Pointer passed back to the callback function

This function will call the specified callback function for once for the base value of DTSTART, and foreach recurring date/time value.

It will filter out events that are specified as an EXDATE or an EXRULE.

## ◆ icalcomponent_get_dtend()

struct icaltimetype icalcomponent_get_dtend | ( | icalcomponent * | comp | ) |

Gets the DTEND property as an icaltime.

If a DTEND property is not present but a DURATION is, we use that to determine the proper end.

If DTSTART is a DATE-TIME with a timezone parameter and a corresponding VTIMEZONE is present in the component, the returned component will already be in the correct timezone; otherwise the caller is responsible for converting it.

For the icalcomponent routines only, dtend and duration are tied together. If you call the get routine for one and the other exists, the routine will calculate the return value. That is, if there is a DTEND and you call get_duration, the routine will return the difference between DTEND and DTSTART.

FIXME this is useless until we can flag the failure

## ◆ icalcomponent_get_dtstart()

struct icaltimetype icalcomponent_get_dtstart | ( | icalcomponent * | comp | ) |

Gets the DTSTART property as an icaltime.

If DTSTART is a DATE-TIME with a timezone parameter and a corresponding VTIMEZONE is present in the component, the returned component will already be in the correct timezone; otherwise the caller is responsible for converting it.

FIXME this is useless until we can flag the failure

## ◆ icalcomponent_get_due()

struct icaltimetype icalcomponent_get_due | ( | icalcomponent * | comp | ) |

Returns the time a VTODO task is DUE.

Parameters

  comp | Valid calendar component.

Uses the DUE: property if it exists, otherwise we calculate the DUE value by adding the task's duration to the DTSTART time.

## ◆ icalcomponent_get_duration()

struct icaldurationtype icalcomponent_get_duration | ( | icalcomponent * | comp | ) |

Gets the DURATION property as an icalduration.

For the icalcomponent routines only, DTEND and DURATION are tied together. If a DURATION property is not present but a DTEND is, we use that to determine the proper end.

For the icalcomponent routines only, dtend and duration are tied together. If you call the get routine for one and the other exists, the routine will calculate the return value. That is, if there is a DTEND and you call get_duration, the routine will return the difference between DTEND and DTSTART.

FIXME We assume DTSTART and DTEND are not in different time zones. Does the standard actually guarantee this?

## ◆ icalcomponent_get_inner()

icalcomponent * icalcomponent_get_inner | ( | icalcomponent * | comp | ) |

Return the first VEVENT, VTODO or VJOURNAL sub-component of cop, or comp if it is one of those types

## ◆ icalcomponent_get_relcalid()

const char * icalcomponent_get_relcalid | ( | icalcomponent * | comp | ) |

Gets the RELCALID property of a component.

Parameters

  comp | Valid calendar component.

## ◆ icalcomponent_get_span()

struct icaltime_span icalcomponent_get_span | ( | icalcomponent * | comp | ) |

Gets the timespan covered by this component, in UTC.

See icalcomponent_foreach_recurrence() for a better way to extract spans from an component.

This method can be called on either a VCALENDAR or any real component. If the VCALENDAR contains no real component, but contains a VTIMEZONE, we return that span instead. This might not be a desirable behavior; we keep it for now for backward compatibility, but it might be deprecated at a future time.

FIXME this API needs to be clarified. DTEND is defined as the first available time after the end of this event, so the span should actually end 1 second before DTEND.

## ◆ icalcomponent_merge_component()

void icalcomponent_merge_component | ( | icalcomponent * | comp,
|  | icalcomponent * | comp_to_merge
| ) |  |

This takes 2 VCALENDAR components and merges the second one into the first, resolving any problems with conflicting TZIDs. comp_to_merge will no longer exist after calling this function.

## ◆ icalcomponent_normalize()

void icalcomponent_normalize | ( | icalcomponent * | comp | ) |

Normalizes (reorders and sorts the properties) the specified icalcomponent `comp`.

Since
  3.0

## ◆ icalcomponent_set_dtend()

void icalcomponent_set_dtend | ( | icalcomponent * | comp,
|  | struct icaltimetype | v
| ) |  |

Sets the DTEND property to given icaltime.

This method respects the icaltime type (DATE vs DATE-TIME) and timezone (or lack thereof).

This also checks that a DURATION property isn't already there, and returns an error if it is. It's the caller's responsibility to remove it.

For the icalcomponent routines only, DTEND and DURATION are tied together. If you call this routine and DURATION exists, no action will be taken and icalerrno will be set to ICAL_MALFORMEDDATA_ERROR. If neither exists, the routine will create the appropriate property.

## ◆ icalcomponent_set_dtstart()

void icalcomponent_set_dtstart | ( | icalcomponent * | comp,
|  | struct icaltimetype | v
| ) |  |

Sets the DTSTART property to the given icaltime,.

This method respects the icaltime type (DATE vs DATE-TIME) and timezone (or lack thereof).

## ◆ icalcomponent_set_due()

void icalcomponent_set_due | ( | icalcomponent * | comp,
|  | struct icaltimetype | v
| ) |  |

Sets the due date of a VTODO task.

Parameters

  comp | Valid VTODO component.
  v | Valid due date time.

The DUE and DURATION properties are tied together:

- If no duration or due properties then sets the DUE property.
- If a DUE property is already set, then resets it to the value v.
- If a DURATION property is already set, then calculates the new duration based on the supplied value of `v`.

## ◆ icalcomponent_set_duration()

void icalcomponent_set_duration | ( | icalcomponent * | comp,
|  | struct icaldurationtype | v
| ) |  |

Sets the DURATION property to given icalduration.

This method respects the icaltime type (DATE vs DATE-TIME) and timezone (or lack thereof).

This also checks that a DTEND property isn't already there, and returns an error if it is. It's the caller's responsibility to remove it.

For the icalcomponent routines only, DTEND and DURATION are tied together. If you call this routine and DTEND exists, no action will be taken and icalerrno will be set to ICAL_MALFORMEDDATA_ERROR. If neither exists, the routine will create the appropriate property.

## ◆ icalcomponent_set_relcalid()

void icalcomponent_set_relcalid | ( | icalcomponent * | comp,
|  | const char * | v
| ) |  |

Sets the RELCALID property of a component.

Parameters

  comp | Valid calendar component.
  v | Relcalid URL value

## ◆ icalproperty_get_datetime_with_component()

struct icaltimetype icalproperty_get_datetime_with_component | ( | icalproperty * | prop,
|  | icalcomponent * | comp
| ) |  |

Gets a DATE or DATE-TIME property as an icaltime.

Computes the datetime corresponding to the specified `icalproperty` and `icalcomponent`. If the property is a DATE-TIME with a TZID parameter and a corresponding VTIMEZONE is present in the component, the returned component will already be in the correct timezone; otherwise the caller is responsible for converting it.

Call icaltime_is_null_time() on the returned value to detect failures.

Since
  3.0.5

If the property is a DATE-TIME with a TZID parameter and a corresponding VTIMEZONE is present in the component, the returned component will already be in the correct timezone; otherwise the caller is responsible for converting it.

The comp can be NULL, in which case the parent of the prop is used to find the corresponding time zone.

## ◆ icalproperty_recurrence_is_excluded()

int icalproperty_recurrence_is_excluded | ( | icalcomponent * | comp,
|  | struct icaltimetype * | dtstart,
|  | struct icaltimetype * | recurtime
| ) |  |

Decides if a recurrence is acceptable.

Parameters

  comp | A valid icalcomponent.
  dtstart | The base dtstart value for this component.
  recurtime | The time to test against.

Returns
  true if the recurrence value is excluded, false otherwise.

This function decides if a specific recurrence value is excluded by EXRULE or EXDATE properties.

It's not the most efficient code. You might get better performance if you assume that recurtime is always increasing for each call. Then you could:

- sort the EXDATE values
- save the state of each EXRULE iterator for the next call.

In this case though you don't need to worry how you call this function. It will always return the correct result.

first test against the exdate values

MATCHED

Now test against the EXRULEs

MATCH

exrule_time > recurtime

## ◆ icalproperty_set_parent()

void icalproperty_set_parent | ( | icalproperty * | property,
|  | icalcomponent * | component
| ) |  |

Sets the parent icalcomponent for the specified icalproperty `property`.

Since
  3.0