|
1 |
|
2 <!DOCTYPE html |
|
3 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|
4 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><meta name="copyright" content="(C) Copyright 2009"/><meta name="DC.rights.owner" content="(C) Copyright 2009"/><meta name="DC.Type" content="mobileconcept"/><meta name="DC.Title" content="Accessing and managing calendar information"/><meta name="DC.Relation" scheme="URI" content="GUID-662F2E2E-9538-42E5-9B5A-5664F1C11A9E"/><meta name="DC.Relation" scheme="URI" content="GUID-E092BF10-C076-4476-9E80-87919940201B"/><meta name="DC.Relation" scheme="URI" content="GUID-1EFD7043-E9B8-4B4E-9EA6-A20B3EECC14A"/><meta name="DC.Relation" scheme="URI" content="GUID-46EABDC1-37CB-412A-ACAD-1A1A9466BB68"/><meta name="DC.Format" content="XHTML"/><meta name="DC.Identifier" content="GUID-AE9A928B-F938-49B5-BC9E-72CB42046571"/><title>Accessing |
|
5 and managing calendar information </title><script type="text/javascript"> |
|
6 function initPage() {} |
|
7 </script><link href="../PRODUCT_PLUGIN/book.css" rel="stylesheet" type="text/css"/><link href="css/s60/style.css" rel="stylesheet" type="text/css" media="all"/></head><body onload="initPage();"><div class="body"><div class="contentLeft prTxt"><h1 class="pageHeading" id="GUID-AE9A928B-F938-49B5-BC9E-72CB42046571">Accessing |
|
8 and managing calendar information</h1><div> |
|
9 <p>The <a href="GUID-CABB28B8-D2B1-496B-BD7E-34FF496E60B4.html#GUID-CABB28B8-D2B1-496B-BD7E-34FF496E60B4">Calendar |
|
10 Service API</a> allows <span>widgets</span> to access, create, and manage |
|
11 calendars and calendar entries stored on a device. You can use the Calendar |
|
12 Service to create <span>widgets</span> that:</p> |
|
13 <ul> |
|
14 <li><p>Retrieve information about calendars and calendar entries</p> |
|
15 </li> |
|
16 <li><p>Create and delete calendars</p></li> |
|
17 <li><p>Create, update, and delete entries for a given calendar</p> |
|
18 </li> |
|
19 <li><p>Import and export calendar entries</p></li> |
|
20 <li><p>Notify the user when calendar entries are created, updated, |
|
21 or deleted</p></li> |
|
22 </ul> |
|
23 <p>Calendar information involves the following concepts:</p> |
|
24 <ul> |
|
25 <li><p><strong>Calendar</strong> stores calendar entries. There can be one |
|
26 or more calendars on a device, and each calendar corresponds to a single file |
|
27 in the device file system.</p></li> |
|
28 <li><p><strong>Calendar entries</strong> make up the main content of a calendar. |
|
29 Each entry belongs to one of the following categories:</p> |
|
30 |
|
31 <ul> |
|
32 <li><p>Anniversary</p></li> |
|
33 <li><p>Event</p></li> |
|
34 <li><p>Meeting</p></li> |
|
35 <li><p>Reminder</p></li> |
|
36 <li><p>To-do item</p></li> |
|
37 </ul> |
|
38 <p>For more information about calendar entries and what they contain, see |
|
39 section <a href="GUID-798E9CA0-2A46-4D10-B567-04C9567500F4.html#GUID-798E9CA0-2A46-4D10-B567-04C9567500F4">Calendar entries</a>.</p> |
|
40 |
|
41 </li> |
|
42 <li><p><strong>Recurring entry</strong> is an entry that has more than one |
|
43 occurrence. The rules of recurrence must be defined separately for each entry. |
|
44 Only meetings can be recurring.</p></li> |
|
45 <li><p><strong>Instance</strong> is a specific occurrence of a recurring entry. |
|
46 Instances are not stored separately (as a rule) but calculated dynamically |
|
47 based on the entry data and rules of recurrence. Non-recurring entries have |
|
48 only a single instance.</p> |
|
49 |
|
50 <p>For example, a weekly meeting that occurs once a week for eight weeks |
|
51 has eight instances. The meeting entry itself is stored only once in the calendar |
|
52 file, but a calendar application can show each meeting instance separately.</p> |
|
53 |
|
54 </li> |
|
55 <li><p><strong>Parent entry</strong> is any original entry. When a new entry |
|
56 is added to a calendar, the entry is stored as a parent entry. A recurring |
|
57 parent entry can have one or more child entries.</p></li> |
|
58 <li><p><strong>Child entry</strong> is a modified instance of a recurring |
|
59 parent entry. When an instance (occurrence) of a recurring entry is explicitly |
|
60 modified, so that it differs in some way from the parent data, it is stored |
|
61 as a child entry. A parent entry and its child entries share the same <code>id</code>, |
|
62 but have unique <code>LocalId</code>s. A child entry always has a |
|
63 single instance.</p> |
|
64 |
|
65 <p>For example, if one of the eight instances of the weekly meeting is |
|
66 modified to occur at a different time of day than the rest, it is stored as |
|
67 a child entry. Since it no longer fully conforms to the parent data and cannot |
|
68 be derived from it, it must be stored as a separate entry.</p> |
|
69 |
|
70 </li> |
|
71 <li><p><strong>Exception</strong> is an occurrence in the original schedule |
|
72 that has been removed and may be replaced with a different occurrence.</p> |
|
73 </li> |
|
74 </ul> |
|
75 <div><h3>Accessing the API and supported methods</h3> |
|
76 <p>To create a <a href="GUID-04095E9A-50E7-4E5F-BD6F-71DA281A0080.html#GUID-04095E9A-50E7-4E5F-BD6F-71DA281A0080">service |
|
77 object</a> for the Calendar Service API, use <code>Service.Calendar</code> to |
|
78 identify the service provider and <code>IDataSource</code> to identify |
|
79 the supported interface:</p> |
|
80 |
|
81 <pre class="codeblock" id="GUID-A2F34B07-1984-45C9-9AB5-72513FDB697B">var so = device.getServiceObject("Service.Calendar", "IDataSource");</pre> |
|
82 <p>The <code>IDataSource</code> interface provides the following |
|
83 methods:</p> |
|
84 <ul> |
|
85 <li><p><a href="GUID-C2E995C2-535C-41A2-B69D-D36009BBE8C4.html#GUID-C2E995C2-535C-41A2-B69D-D36009BBE8C4"><code>GetList()</code></a></p> |
|
86 |
|
87 <p>Use the <code>GetList()</code> method to retrieve information |
|
88 about calendars and calendar entries.</p> |
|
89 |
|
90 </li> |
|
91 <li><p><a href="GUID-4718B87C-0FFF-48EC-A47F-5C9F8C2E2A51.html#GUID-4718B87C-0FFF-48EC-A47F-5C9F8C2E2A51"><code>Add()</code></a></p> |
|
92 |
|
93 <p>Use the <code>Add()</code> method to create a new calendar or |
|
94 calendar entry. You can also use this method to update an existing calendar |
|
95 entry.</p> |
|
96 |
|
97 </li> |
|
98 <li><p><a href="GUID-270C6C2A-5EBB-4ACC-A231-064F17E85F4A.html#GUID-270C6C2A-5EBB-4ACC-A231-064F17E85F4A"><code>Delete()</code></a></p> |
|
99 |
|
100 <p>Use the <code>Delete()</code> method to delete a calendar or |
|
101 one or more entries in a given calendar.</p> |
|
102 |
|
103 </li> |
|
104 <li><p><a href="GUID-D19BB894-371A-4D55-A047-3B2F97673F5F.html#GUID-D19BB894-371A-4D55-A047-3B2F97673F5F"><code>Import()</code></a></p> |
|
105 |
|
106 <p>Use the <code>Import()</code> method to import entries into |
|
107 a calendar. The information must be imported from an iCal or vCal file (see |
|
108 below).</p> |
|
109 |
|
110 </li> |
|
111 <li><p><a href="GUID-890D2F5C-D43F-44B2-97A0-5F5B9230C85F.html#GUID-890D2F5C-D43F-44B2-97A0-5F5B9230C85F"><code>Export()</code></a></p> |
|
112 |
|
113 <p>Use the <code>Export()</code> method to export entries from |
|
114 a calendar. The information is exported to an iCal or vCal file (see below).</p> |
|
115 |
|
116 </li> |
|
117 <li><p><a href="GUID-D4014B08-C48C-48EB-B3A5-1A09FF636B3C.html#GUID-D4014B08-C48C-48EB-B3A5-1A09FF636B3C"><code>RequestNotification()</code></a></p> |
|
118 |
|
119 <p>Use the <code>RequestNotification()</code> method to receive |
|
120 notifications when entries are created, updated, or deleted in a given calendar.</p> |
|
121 |
|
122 </li> |
|
123 <li><p><a href="GUID-0D3A1E17-C699-4A9D-9124-9CEB71E2EBBF.html#GUID-0D3A1E17-C699-4A9D-9124-9CEB71E2EBBF"><code>Cancel()</code></a></p> |
|
124 |
|
125 <p>Use the <code>Cancel()</code> method to cancel an ongoing asynchronous |
|
126 call. This method is valid for any asynchronous call made through the Calendar |
|
127 Service API.</p> |
|
128 |
|
129 </li> |
|
130 </ul> |
|
131 </div> |
|
132 <div><h3>iCal and vCal</h3> |
|
133 <p/> |
|
134 <p>iCalendar (iCal) is an RFC standard for calendar data exchange. It allows |
|
135 for the capture and exchange of information normally stored within a calendar |
|
136 or scheduling application. It allows users to send meeting requests and tasks |
|
137 to other users through email. Recipients of the iCalendar email can respond |
|
138 to the sender easily or counter-propose another meeting date and time. For |
|
139 more information, see the <a href="http://www.ietf.org/rfc/rfc2445.txt" target="_blank">iCalendar |
|
140 specification (RFC 2445)</a>.</p> |
|
141 <p>vCalendar (vCal) is the precursor of the iCalendar standard. It defines |
|
142 a format that allows for the capture of information normally stored within |
|
143 a calendar or scheduling application. The format is suitable as an interchange |
|
144 format between applications or systems and is intended to be used for exchanging |
|
145 information about event and to-do types of entities. For more information, |
|
146 see the <a href="http://www.imc.org/pdi/vcal-10.txt" target="_blank">vCalendar specification</a>.</p> |
|
147 </div> |
|
148 <div><h3>Using the service in a widget</h3> |
|
149 <p>To access and manage calendar information using the Calendar Service |
|
150 API:</p> |
|
151 <ol> |
|
152 <li id="GUID-E8ECDB2F-00C4-488F-A253-87FABDA66CA6-GENIDd0e7244"><a name="GUID-E8ECDB2F-00C4-488F-A253-87FABDA66CA6-GENIDd0e7244"><!----></a><p>Create a service |
|
153 object for the API using <a href="GUID-04095E9A-50E7-4E5F-BD6F-71DA281A0080.html#GUID-04095E9A-50E7-4E5F-BD6F-71DA281A0080"><code>device.getServiceObject()</code></a>.</p> |
|
154 </li> |
|
155 <li id="GUID-0625B45D-A5C9-4ADA-BC21-07963F957A7C-GENIDd0e7253"><a name="GUID-0625B45D-A5C9-4ADA-BC21-07963F957A7C-GENIDd0e7253"><!----></a><p>Define the |
|
156 tasks you want to perform and choose the correct methods for them.</p> |
|
157 </li> |
|
158 <li id="GUID-DBD9997B-CD51-45F9-9ED0-38A98AF08A12-GENIDd0e7258"><a name="GUID-DBD9997B-CD51-45F9-9ED0-38A98AF08A12-GENIDd0e7258"><!----></a><p>Optionally, |
|
159 define how you want the results filtered.</p></li> |
|
160 <li id="GUID-AAB5C193-F848-4B0A-AF03-6BA7425BD10B-GENIDd0e7262"><a name="GUID-AAB5C193-F848-4B0A-AF03-6BA7425BD10B-GENIDd0e7262"><!----></a><p>Define methods |
|
161 for processing the results.</p></li> |
|
162 <li id="GUID-F0C3D20F-6F77-4C88-AF35-39DA70DE701B-GENIDd0e7266"><a name="GUID-F0C3D20F-6F77-4C88-AF35-39DA70DE701B-GENIDd0e7266"><!----></a><p>Use the methods |
|
163 defined in step 2 to perform the tasks. Use asynchronous methods together |
|
164 with <a href="GUID-C7C3B541-8D28-4DC6-9003-ECF57F26C608.html#GUID-C7C3B541-8D28-4DC6-9003-ECF57F26C608"><code>callback()</code></a>.</p> |
|
165 </li> |
|
166 <li id="GUID-0ABE0CB0-D76C-444B-AE53-0D435B3C6E74-GENIDd0e7275"><a name="GUID-0ABE0CB0-D76C-444B-AE53-0D435B3C6E74-GENIDd0e7275"><!----></a><p>Process the |
|
167 results with the methods defined in step 4.</p></li> |
|
168 </ol> |
|
169 <p>For the complete source of a sample widget that demonstrates how to |
|
170 use this service, see <a href="GUID-7C0890BC-7931-417B-B4AC-6E77E65A10F3.html#GUID-7C0890BC-7931-417B-B4AC-6E77E65A10F3">the |
|
171 full example</a>.</p> |
|
172 </div> |
|
173 </div></div></div><div class="footer"><hr/><div class="copy">© Nokia 2009.</div></div></body></html> |