Debian Codegraph @

doc/html/_sources/imap/developer/thoughts/caldav_scheduling_flowchart.rst.txt

raw
1 .. _imap-developer-thoughts-caldavflow:
2
3 .. Note: This document was converted from the original by Nic Bernstein
4 (Onlight). Any formatting mistakes are my fault and not the
5 original author's. Converted via the pandoc tool from HTML.
6
7 Cyrus CalDAV Scheduling Flowchart
8 =================================
9
10 caldav\_put() - create/modify via HTTP PUT on a resource or POST (add-member) on a calendar
11 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
12
13 #. Check if the new resource is a scheduling resource (contains
14 ORGANIZER property). If not, skip to step 4.
15 #. Check for (and load) any existing resource.
16 #. Check if the authenticated user matches ORGANIZER:
17
18 - If yes:
19
20 - If only voter (VPOLL) responses changed, goto
21 `sched\_pollstatus() <#sched_pollstatus>`__.
22 - Otherwise, goto `sched\_request() <#sched_request>`__.
23
24 - Otherwise, goto `sched\_reply() <#sched_reply>`__.
25
26 #. Store the new/modified resource.
27
28 caldav\_delete\_sched() - remove via HTTP DELETE on a resource
29 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
30
31 #. Check if the existing resource is a scheduling resource (has
32 Schedule-Tag). If not, we are done.
33 #. Load the existing resource.
34 #. Check if the authenticated user matches ORGANIZER. If yes, goto
35 `sched\_request() <#sched_request>`__, otherwise goto
36 `sched\_reply() <#sched_reply>`__.
37
38 caldav\_post() - busytime query via HTTP POST on Scheduling Outbox
39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40
41 #. Check the ACL on the owner's Scheduling Outbox. If the authenticated
42 user doesn't have the DACL\_SCHEDFB right, fail.
43 #. `sched\_busytime\_query() <#sched_busytime_query>`__.
44
45 --------------
46
47 sched\_pollstatus - perform a voter response update
48 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
49
50 #.
51
52 --------------
53
54 sched\_request() - perform an organizer request / attendee status update
55 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
56
57 Check the ACL on the owner's Scheduling Outbox. If the authenticated
58 user doesn't have the DACL\_INVITE right, fail.
59
60 If the request includes a resource, then set METHOD:REQUEST, otherwise
61 set METHOD:CANCEL.
62
63 Create an iTIP message template, copying over any CALSCALE property and
64 VTIMEZONE components.
65
66 If not an attendee status update and the existing resource is a
67 scheduling resource: Foreach component in the existing resource, add it
68 and its SEQUENCE to our hash table keyed by RECURRENCE-ID (for
69 comparison against new/modified resource).
70
71 Create a hash table of attendees. This will hold attendee-specific iTIP
72 messages.
73
74 Foreach component in the new/modified resource:
75
76 a. Lookup (by RECURRENCE-ID) and remove the component from the hash
77 table of existing components.
78 b. If the component exists compare all of DTSTART, DTEND, DURATION,
79 RRULE, RDATE, EXDATE to those of the new component.
80 c. If the component is new or changed, then
81 `process\_attendees() <#process_attendees>`__.
82
83 Foreach remaining component in the hash table of existing components do
84 `sched\_cancel() <#sched_cancel>`__.
85
86 Foreach iTIP message in our hash table of ATTENDEES,
87 `sched\_deliver() <#sched_deliver>`__ the iTIP message.
88
89 Foreach component in the new/modified resource update the
90 SCHEDULE-STATUS of each ATTENDEE.
91
92 process\_attendees() - create a suitable iTIP request message for each attendee
93 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
94
95 Foreach ATTENDEE in the component, remove the SCHEDULE-STATUS parameter,
96 and set PROPSTAT=NEEDS-ACTION if required.
97
98 Make a copy of the component and
99 `clean\_component() <#clean_component>`__.
100
101 Foreach ATTENDEE in the cleaned component:
102
103 a. Check the CalDAV Scheduling parameters. If SCHEDULE-AGENT != SERVER,
104 skip to the next attendee.
105 b. Lookup attendee in our hash table.
106 c. If it doesn't exist, create a clone of our iTIP template and insert
107 it into our hash table of attendees.
108 d. Add the component to the attendee's iTIP message.
109 e. Add the component “number” to our mask of new components appearing in
110 the attendee's iTIP message.
111
112 If the component is not the "master", foreach attendee do
113 `sched\_exclude() <#sched_exclude>`__.
114
115 sched\_exclude() - exclude an attendee from a recurrence instance
116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117
118 #. If the component did not appear in the attendee's iTIP message, add
119 an EXDATE property (based on the RECURRENCE-ID of the component) to
120 the master component of the attendee's iTIP message.
121
122 sched\_cancel() - cancel an organizer event/task
123 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
124
125 #. Set STATUS:CANCELLED on the component.
126 #. `process\_attendees() <#process_attendees>`__.
127
128 --------------
129
130 sched\_reply() - perform an attendee reply
131 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
132
133 Check the CalDAV Scheduling parameters on ORGANIZER. If SCHEDULE-AGENT
134 != SERVER, we are done.
135
136 Check the ACL on the owner's Scheduling Outbox. If the authenticated
137 user doesn't have the DACL\_REPLY right, fail.
138
139 Create a new iTIP (METHOD:REPLY) message, copying over any CALSCALE
140 property and VTIMEZONE components.
141
142 Foreach component in the existing resource:
143
144 a. `trim\_attendees() <#trim_attendees>`__.
145 b. Add the trimmed component and the attendee's PARTSTAT to our hash
146 table keyed by RECURRENCE-ID (for comparison against new/modified
147 resource).
148
149 Foreach component in the new/modified resource:
150
151 `trim\_attendees() <#trim_attendees>`__.
152
153 Lookup (by RECURRENCE-ID) and remove the component from the hash table
154 of existing components.
155
156 If the component exists:
157
158 i. If component is VPOLL, add voter responses to REPLY via
159 `sched\_vpoll\_reply(). <#sched_vpoll_reply>`__
160 ii. Otherwise, compare the PARTSTAT of the ATTENDEE to that of the new
161 component.
162
163 If the component is new or the PARTSTAT has changed:
164
165 i. `clean\_component() <#clean_component>`__.
166 ii. Add the component to our iTIP message.
167 iii. Add the component “number” to our mask of new components appearing
168 in our iTIP message.
169
170 Foreach remaining component in the hash table of existing components do
171 `sched\_decline() <#sched_decline>`__.
172
173 `sched\_deliver() <#sched_deliver>`__ our iTIP message.
174
175 Foreach component in the new/modified resource that appeared in our iTIP
176 message, update the SCHEDULE-STATUS of the ORGANIZER.
177
178 trim\_attendees() - remove all attendees other than the one replying
179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
180
181 #. Clone the component and remove all ATTENDEE properties other than the
182 one corresponding to the owner of the calendar.
183 #. Return the ATTENDEE property of owner, his/her PARTSTAT parameter,
184 and the RECURRENCE-ID of the component.
185
186 sched\_vpoll\_reply() - add voter responses to VPOLL reply
187 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
188
189 #.
190
191 sched\_decline() - decline a recurrence instance for an attendee
192 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
193
194 #. Set PARTSTAT of ATTENDEE to DECLINED.
195 #. `clean\_component() <#clean_component>`__.
196 #. Add the component to our iTIP message.
197
198 --------------
199
200 clean\_component() - sanitize a component for use in an iTIP message
201 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
202
203 #. Update DTSTAMP.
204 #. Remove any VALARM components.
205 #. For a reply/decline only, remove scheduling parameters from
206 ORGANIZER.
207
208 sched\_deliver() - deliver an iTIP message to a recipient
209 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
210
211 #. Lookup the recipient.
212 #. If local to our server goto
213 `sched\_deliver\_local() <#sched_deliver_local>`__, otherwise goto
214 `sched\_deliver\_remote() <#sched_deliver_remote>`__.
215
216 --------------
217
218 sched\_deliver\_local() - deliver an iTIP message to a local user
219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
220
221 Check the ACL on the owner's Scheduling Inbox. If the sender doesn't
222 have the proper right (DACL\_INVITE for request/cancel, DACL\_REPLY for
223 reply), fail.
224
225 Search the recipient's calendars for a resource having the specified
226 UID.
227
228 If the resource doesn't exist:
229
230 a. If the iTIP method is REPLY, fail (we are done).
231 b. If the iTIP method is CANCEL, ignore it (we are done).
232 c. Otherwise, create a new (empty) attendee object and target the
233 recipient's Default calendar.
234
235 Otherwise, load the existing resource.
236
237 Update the new/existing resource:
238
239 a. If the iTIP method is CANCEL, set STATUS:CANCELLED on all existing
240 components.
241 b. If the iTIP method is REPLY, do
242 `deliver\_merge\_reply() <#deliver_merge_reply>`__.
243 c. If the iTIP method is REQUEST, do
244 `deliver\_merge\_request() <#deliver_merge_request>`__.
245 d. If the iTIP method is POLLSTATUS, do
246 `deliver\_merge\_pollstatus() <#deliver_merge_pollstatus>`__.
247
248 Store the new/updated resource in the recipient's target calendar.
249
250 Record the delivery status (SCHEDULE-STATUS).
251
252 If the iTIP message is something other than just a PARTSTAT update from
253 an attendee, store the iTIP message as a new resource in the recipient's
254 Inbox.
255
256 If the iTIP method is REPLY, send an update other attendees via
257 `sched\_pollstatus() <#sched_pollstatus>`__ (VPOLL only) or
258 `sched\_request() <#sched_request>`__.
259
260 deliver\_merge\_reply() - update an organizer resource with an attendee reply
261 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
262
263 Foreach component in the existing resource, add it to our hash table
264 keyed by RECURRENCE-ID (for comparison against iTIP message).
265
266 Foreach component in the iTIP message:
267
268 Lookup (by RECURRENCE-ID) the component from the hash table of existing
269 components.
270
271 If the component doesn't exist (new recurrence overridden by ATTENDEE)
272 create a new recurring component:
273
274 i. Clone the existing master component.
275 ii. Remove the RRULE property.
276 iii. Add the RECURRENCE-ID from the iTIP message.
277 iv. Replace the DTSTART, DTEND, SEQUENCE properties with those from the
278 iTIP message.
279 v. Add the new component to our existing resource.
280
281 Get the sending ATTENDEE from the iTIP message.
282
283 Find the matching ATTENDEE in the existing component.
284
285 If not found (ATTENDEE added themselves to this recurrence), add new
286 ATTENDEE to the component.
287
288 Set the ATTENDEE PARTSTAT, RSVP, and SCHEDULE-STATUS parameters in the
289 existing component.
290
291 If the component is VPOLL, update the voter responses in the existing
292 component via
293 `deliver\_merge\_vpoll\_reply() <#deliver_merge_vpoll_reply>`__.
294
295 Return the sending ATTENDEE.
296
297 deliver\_merge\_vpoll\_reply() - update an organizer resource with voter responses
298 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
299
300 #. Foreach sub-component in the existing resource, replace any voter
301 response(s) with those from the reply.
302
303 deliver\_merge\_request() - create/update an attendee resource with an organizer request
304 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
305
306 Foreach VTIMEZONE component in the existing resource, add it to our hash
307 table keyed by TZID (for comparison against iTIP message).
308
309 Foreach VTIMEZONE component in the iTIP message:
310
311 a. Lookup (by TZID) the VTIMEZONE component from the hash table of
312 existing components.
313 b. If the component exists, remove it from the existing object.
314 c. Add the VTIMEZONE from the iTIP message to our existing object.
315
316 Foreach component in the existing resource, add it to our hash table
317 keyed by RECURRENCE-ID (for comparison against iTIP message).
318
319 Foreach component in the iTIP message:
320
321 Clone a new component from the iTIP component.
322
323 Lookup (by RECURRENCE-ID) the component from the hash table of existing
324 components.
325
326 If the component exists:
327
328 i. Compare the SEQUENCE of the new component to the existing component
329 to see if it has changed.
330 ii. Copy any COMPLETED, PERCENT-COMPLETE, or TRANSP properties from the
331 existing component to the new component.
332 iii. Copy any ORGANIZER SCHEDULE-STATUS parameter from the existing
333 component to the new component.
334 iv. Remove the existing component from the existing object.
335
336 Add the new component to the existing object.
337
338 deliver\_merge\_pollstatus() - update voter responses on a voter resource
339 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
340
341 Foreach sub-component in the existing resource, add it to our hash table
342 keyed by POLL-ITEM-ID (for comparison against iTIP message). The
343 sub-component entry includes a hash table of VOTERs.
344
345 Foreach sub-component in the iTIP message:
346
347 a. Lookup (by POLL-ITEM-ID) the sub-component from the hash table of
348 existing sub-components.
349 b. If the component exists, foreach VOTER in the sub-component in the
350 iTIP message:
351
352 i. Lookup VOTER in the hash table of existing sub-component.
353 ii. Add/update VOTER response.
354
355 --------------
356
357 sched\_deliver\_remote() - deliver an iTIP message to a remote user
358 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
359
360 #. If the recipient is local to our Murder, goto
361 `isched\_send() <#isched_send>`__, otherwise goto
362 `imip\_send() <#imip_send>`__.
363 #. Retrieve status of iTIP message delivery.
364
365 isched\_send() - deliver an iTIP message to a remote user via iSchedule (HTTP)
366 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
367
368 imip\_send() - deliver an iTIP message to a remote user via iMIP (SMTP)
369 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
370
371 sched\_busytime\_query() - perform a busytime query
372 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
373
374 busytime\_query\_local() - perform a busytime query on a local user
375 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
376
377 busytime\_query\_remote() - perform a busytime query on a remote user
378 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~