← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to docs/reference/calendar/libecal/xml/e-cal-check-timezones.xml

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/calendar/libecal/xml/e-cal-check-timezones.xml
1
 
<?xml version="1.0"?>
2
 
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
3
 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4
 
<refentry id="libecal-e-cal-check-timezones">
5
 
<refmeta>
6
 
<refentrytitle role="top_of_page" id="libecal-e-cal-check-timezones.top_of_page">e-cal-check-timezones</refentrytitle>
7
 
<manvolnum>3</manvolnum>
8
 
<refmiscinfo>
9
 
  LIBECAL Library
10
 
</refmiscinfo>
11
 
</refmeta>
12
 
<refnamediv>
13
 
<refname>e-cal-check-timezones</refname>
14
 
<refpurpose></refpurpose>
15
 
</refnamediv>
16
 
 
17
 
<refsynopsisdiv id="libecal-e-cal-check-timezones.synopsis" role="synopsis">
18
 
<title role="synopsis.title">Synopsis</title>
19
 
 
20
 
<synopsis><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>            <link linkend="e-cal-check-timezones">e_cal_check_timezones</link>               (<parameter><link linkend="icalcomponent"><type>icalcomponent</type></link> *comp</parameter>,
21
 
                                                         <parameter><link linkend="GList"><type>GList</type></link> *comps</parameter>,
22
 
                                                         <parameter><link linkend="icaltimezone"><type>icaltimezone</type></link>* (tzlookupconst gchar *tzid, gconstpointer custom, GError **error) ()</parameter>,
23
 
                                                         <parameter><link linkend="gconstpointer"><type>gconstpointer</type></link> custom</parameter>,
24
 
                                                         <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);
25
 
<link linkend="icaltimezone"><returnvalue>icaltimezone</returnvalue></link> *      <link linkend="e-cal-tzlookup-ecal">e_cal_tzlookup_ecal</link>                 (<parameter>const <link linkend="gchar"><type>gchar</type></link> *tzid</parameter>,
26
 
                                                         <parameter><link linkend="gconstpointer"><type>gconstpointer</type></link> custom</parameter>,
27
 
                                                         <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);
28
 
<link linkend="icaltimezone"><returnvalue>icaltimezone</returnvalue></link> *      <link linkend="e-cal-tzlookup-icomp">e_cal_tzlookup_icomp</link>                (<parameter>const <link linkend="gchar"><type>gchar</type></link> *tzid</parameter>,
29
 
                                                         <parameter><link linkend="gconstpointer"><type>gconstpointer</type></link> custom</parameter>,
30
 
                                                         <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);
31
 
const <link linkend="gchar"><returnvalue>gchar</returnvalue></link> *       <link linkend="e-cal-match-tzid">e_cal_match_tzid</link>                    (<parameter>const <link linkend="gchar"><type>gchar</type></link> *tzid</parameter>);
32
 
</synopsis>
33
 
</refsynopsisdiv>
34
 
 
35
 
<refsect1 id="libecal-e-cal-check-timezones.description" role="desc">
36
 
<title role="desc.title">Description</title>
37
 
<para>
38
 
</para>
39
 
</refsect1>
40
 
<refsect1 id="libecal-e-cal-check-timezones.details" role="details">
41
 
<title role="details.title">Details</title>
42
 
<refsect2 id="e-cal-check-timezones" role="function">
43
 
<title>e_cal_check_timezones ()</title>
44
 
<indexterm zone="e-cal-check-timezones"><primary>e_cal_check_timezones</primary></indexterm>
45
 
<programlisting><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>            e_cal_check_timezones               (<parameter><link linkend="icalcomponent"><type>icalcomponent</type></link> *comp</parameter>,
46
 
                                                         <parameter><link linkend="GList"><type>GList</type></link> *comps</parameter>,
47
 
                                                         <parameter><link linkend="icaltimezone"><type>icaltimezone</type></link>* (tzlookupconst gchar *tzid, gconstpointer custom, GError **error) ()</parameter>,
48
 
                                                         <parameter><link linkend="gconstpointer"><type>gconstpointer</type></link> custom</parameter>,
49
 
                                                         <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
50
 
<para>
51
 
This function cleans up VEVENT, VJOURNAL, VTODO and VTIMEZONE
52
 
items which are to be imported into Evolution.
53
 
</para>
54
 
<para>
55
 
Using VTIMEZONE definitions is problematic because they cannot be
56
 
updated properly when timezone definitions change. They are also
57
 
incomplete (for compatibility reason only one set of rules for
58
 
summer saving changes can be included, even if different rules
59
 
apply in different years). This function looks for matches of the
60
 
used TZIDs against system timezones and replaces such TZIDs with
61
 
the corresponding system timezone. This works for TZIDs containing
62
 
a location (found via a fuzzy string search) and for Outlook TZIDs
63
 
(via a hard-coded lookup table).
64
 
</para>
65
 
<para>
66
 
Some programs generate broken meeting invitations with TZID, but
67
 
without including the corresponding VTIMEZONE. Importing such
68
 
invitations unchanged causes problems later on (meeting displayed
69
 
incorrectly, <link linkend="e-cal-get-component-as-string"><type>e_cal_get_component_as_string</type></link> fails). The situation
70
 
where this occurred in the past (found by a SyncEvolution user) is
71
 
now handled via the location based mapping.
72
 
</para>
73
 
<para>
74
 
If this mapping fails, this function also deals with VTIMEZONE
75
 
conflicts: such conflicts occur when the calendar already contains
76
 
an old VTIMEZONE definition with the same TZID, but different
77
 
summer saving rules. Replacing the VTIMEZONE potentially breaks
78
 
displaying of old events, whereas not replacing it breaks the new
79
 
events (the behavior in Evolution &lt;= 2.22.1).
80
 
</para>
81
 
<para>
82
 
The way this problem is resolved is by renaming the new VTIMEZONE
83
 
definition until the TZID is unique. A running count is appended to
84
 
the TZID. All items referencing the renamed TZID are adapted
85
 
accordingly.</para>
86
 
<variablelist role="params">
87
 
<varlistentry><term><parameter>comp</parameter>&#160;:</term>
88
 
<listitem><simpara>a VCALENDAR containing a list of
89
 
           VTIMEZONE and arbitrary other components, in
90
 
           arbitrary order: these other components are
91
 
           modified by this call
92
 
</simpara></listitem></varlistentry>
93
 
<varlistentry><term><parameter>comps</parameter>&#160;:</term>
94
 
<listitem><simpara>a list of icalcomponent instances which
95
 
           also have to be patched; may be NULL
96
 
</simpara></listitem></varlistentry>
97
 
<varlistentry><term><parameter>custom</parameter>&#160;:</term>
98
 
<listitem><simpara>an arbitrary pointer which is passed through to
99
 
           the tzlookup function
100
 
</simpara></listitem></varlistentry>
101
 
<varlistentry><term><parameter>error</parameter>&#160;:</term>
102
 
<listitem><simpara>an error description in case of a failure
103
 
</simpara></listitem></varlistentry>
104
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> TRUE if successful, FALSE otherwise.
105
 
</simpara></listitem></varlistentry>
106
 
</variablelist></refsect2>
107
 
<refsect2 id="e-cal-tzlookup-ecal" role="function">
108
 
<title>e_cal_tzlookup_ecal ()</title>
109
 
<indexterm zone="e-cal-tzlookup-ecal"><primary>e_cal_tzlookup_ecal</primary></indexterm>
110
 
<programlisting><link linkend="icaltimezone"><returnvalue>icaltimezone</returnvalue></link> *      e_cal_tzlookup_ecal                 (<parameter>const <link linkend="gchar"><type>gchar</type></link> *tzid</parameter>,
111
 
                                                         <parameter><link linkend="gconstpointer"><type>gconstpointer</type></link> custom</parameter>,
112
 
                                                         <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
113
 
<para>
114
 
An implementation of the tzlookup callback which clients
115
 
can use. Calls <link linkend="e-cal-get-timezone"><type>e_cal_get_timezone</type></link>.</para>
116
 
<variablelist role="params">
117
 
<varlistentry><term><parameter>tzid</parameter>&#160;:</term>
118
 
<listitem><simpara>
119
 
</simpara></listitem></varlistentry>
120
 
<varlistentry><term><parameter>custom</parameter>&#160;:</term>
121
 
<listitem><simpara>must be a valid ECal pointer
122
 
</simpara></listitem></varlistentry>
123
 
<varlistentry><term><parameter>error</parameter>&#160;:</term>
124
 
<listitem><simpara>
125
 
</simpara></listitem></varlistentry>
126
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
127
 
</simpara></listitem></varlistentry>
128
 
</variablelist></refsect2>
129
 
<refsect2 id="e-cal-tzlookup-icomp" role="function">
130
 
<title>e_cal_tzlookup_icomp ()</title>
131
 
<indexterm zone="e-cal-tzlookup-icomp"><primary>e_cal_tzlookup_icomp</primary></indexterm>
132
 
<programlisting><link linkend="icaltimezone"><returnvalue>icaltimezone</returnvalue></link> *      e_cal_tzlookup_icomp                (<parameter>const <link linkend="gchar"><type>gchar</type></link> *tzid</parameter>,
133
 
                                                         <parameter><link linkend="gconstpointer"><type>gconstpointer</type></link> custom</parameter>,
134
 
                                                         <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
135
 
<para>
136
 
An implementation of the tzlookup callback which backends
137
 
like the file backend can use. Searches for the timezone
138
 
in the component list.</para>
139
 
<variablelist role="params">
140
 
<varlistentry><term><parameter>tzid</parameter>&#160;:</term>
141
 
<listitem><simpara>
142
 
</simpara></listitem></varlistentry>
143
 
<varlistentry><term><parameter>custom</parameter>&#160;:</term>
144
 
<listitem><simpara>must be a icalcomponent pointer which contains
145
 
         either a VCALENDAR with VTIMEZONEs or VTIMEZONES
146
 
         directly
147
 
</simpara></listitem></varlistentry>
148
 
<varlistentry><term><parameter>error</parameter>&#160;:</term>
149
 
<listitem><simpara>
150
 
</simpara></listitem></varlistentry>
151
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
152
 
</simpara></listitem></varlistentry>
153
 
</variablelist></refsect2>
154
 
<refsect2 id="e-cal-match-tzid" role="function">
155
 
<title>e_cal_match_tzid ()</title>
156
 
<indexterm zone="e-cal-match-tzid"><primary>e_cal_match_tzid</primary></indexterm>
157
 
<programlisting>const <link linkend="gchar"><returnvalue>gchar</returnvalue></link> *       e_cal_match_tzid                    (<parameter>const <link linkend="gchar"><type>gchar</type></link> *tzid</parameter>);</programlisting>
158
 
<variablelist role="params">
159
 
<varlistentry><term><parameter>tzid</parameter>&#160;:</term>
160
 
<listitem><simpara>
161
 
</simpara></listitem></varlistentry>
162
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
163
 
</simpara></listitem></varlistentry>
164
 
</variablelist></refsect2>
165
 
 
166
 
</refsect1>
167
 
 
168
 
</refentry>