<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="libecal-e-cal-check-timezones">
<refmeta>
<refentrytitle role="top_of_page" id="libecal-e-cal-check-timezones.top_of_page">e-cal-check-timezones</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBECAL Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>e-cal-check-timezones</refname>
<refpurpose></refpurpose>
</refnamediv>

<refsynopsisdiv id="libecal-e-cal-check-timezones.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
<link linkend="gboolean">gboolean</link>            <link linkend="e-cal-check-timezones">e_cal_check_timezones</link>               (<link linkend="icalcomponent">icalcomponent</link> *comp,
                                                         <link linkend="GList">GList</link> *comps,
                                                         <link linkend="icaltimezone">icaltimezone</link>* (tzlookupconst char *tzid,const void *custom,GError **error) (),
                                                         const <link linkend="void">void</link> *custom,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="icaltimezone">icaltimezone</link> *      <link linkend="e-cal-tzlookup-ecal">e_cal_tzlookup_ecal</link>                 (const <link linkend="char">char</link> *tzid,
                                                         const <link linkend="void">void</link> *custom,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="icaltimezone">icaltimezone</link> *      <link linkend="e-cal-tzlookup-icomp">e_cal_tzlookup_icomp</link>                (const <link linkend="char">char</link> *tzid,
                                                         const <link linkend="void">void</link> *custom,
                                                         <link linkend="GError">GError</link> **error);
const <link linkend="char">char</link> *        <link linkend="e-cal-match-tzid">e_cal_match_tzid</link>                    (const <link linkend="char">char</link> *tzid);
</synopsis>
</refsynopsisdiv>









<refsect1 id="libecal-e-cal-check-timezones.description" role="desc">
<title role="desc.title">Description</title>
<para>
</para>
</refsect1>

<refsect1 id="libecal-e-cal-check-timezones.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="e-cal-check-timezones" role="function">
<title>e_cal_check_timezones ()</title>
<indexterm zone="e-cal-check-timezones"><primary sortas="e_cal_check_timezones">e_cal_check_timezones</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            e_cal_check_timezones               (<link linkend="icalcomponent">icalcomponent</link> *comp,
                                                         <link linkend="GList">GList</link> *comps,
                                                         <link linkend="icaltimezone">icaltimezone</link>* (tzlookupconst char *tzid,const void *custom,GError **error) (),
                                                         const <link linkend="void">void</link> *custom,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
This function cleans up VEVENT, VJOURNAL, VTODO and VTIMEZONE
items which are to be imported into Evolution.
</para>
<para>
Using VTIMEZONE definitions is problematic because they cannot be
updated properly when timezone definitions change. They are also
incomplete (for compatibility reason only one set of rules for
summer saving changes can be included, even if different rules
apply in different years). This function looks for matches of the
used TZIDs against system timezones and replaces such TZIDs with
the corresponding system timezone. This works for TZIDs containing
a location (found via a fuzzy string search) and for Outlook TZIDs
(via a hard-coded lookup table).
</para>
<para>
Some programs generate broken meeting invitations with TZID, but
without including the corresponding VTIMEZONE. Importing such
invitations unchanged causes problems later on (meeting displayed
incorrectly, <link linkend="e-cal-get-component-as-string"><type>e_cal_get_component_as_string</type></link> fails). The situation
where this occurred in the past (found by a SyncEvolution user) is
now handled via the location based mapping.
</para>
<para>
If this mapping fails, this function also deals with VTIMEZONE
conflicts: such conflicts occur when the calendar already contains
an old VTIMEZONE definition with the same TZID, but different
summer saving rules. Replacing the VTIMEZONE potentially breaks
displaying of old events, whereas not replacing it breaks the new
events (the behavior in Evolution &lt;= 2.22.1).
</para>
<para>
The way this problem is resolved is by renaming the new VTIMEZONE
definition until the TZID is unique. A running count is appended to
the TZID. All items referencing the renamed TZID are adapted
accordingly.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>comp</parameter>&#160;:</term>
<listitem><simpara>     a VCALENDAR containing a list of
           VTIMEZONE and arbitrary other components, in
           arbitrary order: these other components are
           modified by this call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>comps</parameter>&#160;:</term>
<listitem><simpara>    a list of icalcomponent instances which
           also have to be patched; may be NULL
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>tzlookup</parameter>&#160;:</term>
<listitem><simpara> a callback function which is called to retrieve
           a calendar's VTIMEZONE definition; the returned
           definition is *not* freed by <link linkend="e-cal-check-timezones"><function>e_cal_check_timezones()</function></link>
           (to be compatible with <link linkend="e-cal-get-timezone"><function>e_cal_get_timezone()</function></link>);
           NULL indicates that no such timezone exists
           or an error occurred
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>custom</parameter>&#160;:</term>
<listitem><simpara>   an arbitrary pointer which is passed through to
           the tzlookup function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara>    an error description in case of a failure
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> TRUE if successful, FALSE otherwise.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-cal-tzlookup-ecal" role="function">
<title>e_cal_tzlookup_ecal ()</title>
<indexterm zone="e-cal-tzlookup-ecal"><primary sortas="e_cal_tzlookup_ecal">e_cal_tzlookup_ecal</primary></indexterm><programlisting><link linkend="icaltimezone">icaltimezone</link> *      e_cal_tzlookup_ecal                 (const <link linkend="char">char</link> *tzid,
                                                         const <link linkend="void">void</link> *custom,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
An implementation of the tzlookup callback which clients
can use. Calls <link linkend="e-cal-get-timezone"><type>e_cal_get_timezone</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tzid</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>custom</parameter>&#160;:</term>
<listitem><simpara> must be a valid ECal pointer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-cal-tzlookup-icomp" role="function">
<title>e_cal_tzlookup_icomp ()</title>
<indexterm zone="e-cal-tzlookup-icomp"><primary sortas="e_cal_tzlookup_icomp">e_cal_tzlookup_icomp</primary></indexterm><programlisting><link linkend="icaltimezone">icaltimezone</link> *      e_cal_tzlookup_icomp                (const <link linkend="char">char</link> *tzid,
                                                         const <link linkend="void">void</link> *custom,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
An implementation of the tzlookup callback which backends
like the file backend can use. Searches for the timezone
in the component list.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tzid</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>custom</parameter>&#160;:</term>
<listitem><simpara> must be a icalcomponent pointer which contains
         either a VCALENDAR with VTIMEZONEs or VTIMEZONES
         directly
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-cal-match-tzid" role="function">
<title>e_cal_match_tzid ()</title>
<indexterm zone="e-cal-match-tzid"><primary sortas="e_cal_match_tzid">e_cal_match_tzid</primary></indexterm><programlisting>const <link linkend="char">char</link> *        e_cal_match_tzid                    (const <link linkend="char">char</link> *tzid);</programlisting>
<para>
</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tzid</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
