-
Notifications
You must be signed in to change notification settings - Fork 0
/
draft-ietf-calext-valarm-extensions.xml
1025 lines (901 loc) · 38.8 KB
/
draft-ietf-calext-valarm-extensions.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'
[
<!ENTITY rfc2119 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc3261 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3261.xml'>
<!ENTITY rfc3860 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3860.xml'>
<!ENTITY rfc3966 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3966.xml'>
<!ENTITY rfc4791 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4791.xml'>
<!ENTITY rfc5545 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5545.xml'>
<!ENTITY rfc5546 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5546.xml'>
<!ENTITY rfc5724 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5724.xml'>
<!ENTITY rfc5870 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5870.xml'>
<!ENTITY rfc7986 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7986.xml'>
<!ENTITY rfc8174 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml'>
<!ENTITY idEventPub PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-calext-eventpub-extensions.xml'>
]>
<?rfc toc="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc tocdepth="2"?>
<?rfc strict="yes"?>
<rfc category="std" updates='5545'
ipr='trust200902' docName='draft-ietf-calext-valarm-extensions-07'>
<front>
<title abbrev="VALARM Extensions">VALARM Extensions for iCalendar</title>
<author initials="C." surname="Daboo" fullname="Cyrus Daboo">
<organization abbrev="Apple">Apple Inc.</organization>
<address>
<postal>
<street>1 Infinite Loop</street>
<city>Cupertino</city>
<region>CA</region>
<code>95014</code>
<country>USA</country>
</postal>
<email>[email protected]</email>
<uri>http://www.apple.com/</uri>
</address>
</author>
<author role="editor" initials="K." surname="Murchison"
fullname="Kenneth Murchison">
<organization abbrev="Fastmail">Fastmail US LLC</organization>
<address>
<postal>
<street>1429 Walnut St, Suite 1201</street>
<city>Philadephia</city>
<region>PA</region>
<code>19102</code>
<country>USA</country>
</postal>
<email>[email protected]</email>
<uri>http://www.fastmail.com/</uri>
</address>
</author>
<date />
<area>Applications</area>
<keyword>alarms</keyword>
<keyword>calendaring</keyword>
<keyword>iCalendar</keyword>
<keyword>CalDAV</keyword>
<abstract>
<t>This document defines a set of extensions to the iCalendar
VALARM component to enhance use of alarms and improve
interoperability between clients and servers.</t>
<t>This document updates RFC5545.</t>
</abstract>
</front>
<middle>
<section title='Introduction'>
<t>The <xref target="RFC5545">iCalendar</xref> specification
defines a set of components used to describe calendar data. One
of those is the "VALARM" component which appears as a
sub-component of "VEVENT" and "VTODO" components. The "VALARM"
component is used to specify a reminder for an event or
task. Different alarm actions are possible, as are different
ways to specify how the alarm is triggered.</t>
<t>As iCalendar has become more widely used and as client-server
protocols such as <xref target="RFC4791">CalDAV</xref> have
become more prevalent, several issues with "VALARM" components
have arisen. Most of these relate to the need to extend the
existing "VALARM" component with new properties and behaviors to
allow clients and servers to accomplish specific tasks in an
interoperable manner. For example, clients typically need a way
to specify that an alarm has been dismissed by a calendar user,
or has been "snoozed" by a set amount of time. To date, this has
been done through the use of custom "X-" properties specific to
each client implementation, leading to poor
interoperability.</t>
<t>This specification defines a set of extensions to "VALARM"
components to cover common requirements for alarms not currently
addressed in iCalendar. Each extension is defined in a separate
section below. For the most part, each extension can be
supported independently of the others, though in some cases one
extension will require another. In addition, this specification
describes mechanisms by which clients can interoperably
implement common features such as "snoozing".</t>
</section>
<section title='Conventions Used in This Document'>
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in BCP 14
<xref target='RFC2119' /> <xref target='RFC8174' />
when, and only when, they appear in all capitals, as shown here.</t>
<t>When XML element types in the namespaces "DAV:" and
"urn:ietf:params:xml:ns:caldav" are referenced in this document
outside of the context of an XML fragment, the string "DAV:" and
"CALDAV:" will be prefixed to the element type names
respectively.</t>
</section>
<section title="Extensible syntax for VALARM" anchor="syntax">
<t>Section 3.6.6 of <xref target="RFC5545" /> defines the syntax
for "VALARM" components and properties within them. However, as
written, it is hard to extend this by adding, e.g., a new
property common to all types of alarm. Since many of the
extensions defined in this document need to extend the base
syntax, an alternative form for the base syntax is defined here,
with the goal of simplifying specification of the extensions
while augmenting the existing functionality defined in
<xref target="RFC5545"/> to allow for nested sub-components
(as required by
<xref target="proximity">proximity alarm triggers</xref>).</t>
<t>A "VALARM" calendar component is re-defined by the following notation:
<figure>
<artwork name="abnf"><![CDATA[
alarmcext = "BEGIN" ":" "VALARM" CRLF
*alarmprop *alarm-subcomp
"END" ":" "VALARM" CRLF
alarmprop = (
; the following are REQUIRED,
; but MUST NOT occur more than once
action / trigger /
; one set of action properties MUST be
; present and MUST match the action specified
; in the ACTION property
actionprops /
; the following are OPTIONAL,
; and MAY occur more than once
x-prop / iana-prop
)
actionprops = *audiopropext / *disppropext / *emailpropext
audiopropext = (
; 'duration' and 'repeat' are both OPTIONAL,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat /
; the following is OPTIONAL,
; but MUST NOT occur more than once
attach
)
disppropext = (
; the following are REQUIRED,
; but MUST NOT occur more than once
description /
; 'duration' and 'repeat' are both OPTIONAL,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat
)
emailpropext = (
; the following are all REQUIRED,
; but MUST NOT occur more than once
description / summary /
; the following is REQUIRED,
; and MAY occur more than once
attendee /
; 'duration' and 'repeat' are both OPTIONAL,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat
; the following is OPTIONAL,
; and MAY occur more than once
attach
)
alarm-subcomp = (
; the following are OPTIONAL,
; and MAY occur more than once
x-comp / iana-comp
)
]]></artwork>
</figure></t>
</section>
<section title="Alarm Unique Identifier" anchor="uid">
<t>This extension adds a "UID"
property to "VALARM" components to allow a unique identifier to
be specified. The value of this property can then be used to refer
uniquely to the "VALARM" component.</t>
<t>The "UID" property defined here follows the definition in
Section 3.8.4.7 of <xref target="RFC5545" /> with the security
and privacy updates in Section 5.3 of <xref target="RFC7986" />.
In particular it MUST be a globally unique identifier that does
not contain any security- or privacy-sensitive information.</t>
<t>The "VALARM" component defined in <xref target="syntax" /> is
extended here as:
<figure>
<artwork name="abnf"><![CDATA[
alarmprop =/ (
; the following is OPTIONAL,
; but MUST NOT occur more than once
uid
)
]]></artwork>
</figure></t>
</section>
<section title="Alarm Related To" anchor="RELATED">
<t>It is often convenient to relate one or more "VALARM"
components to other "VALARM" components (e.g., see <xref
target="snooze"/>). This can be accomplished if the "VALARM"
components each have their own "UID" property (as per <xref
target="uid" />).</t>
<t>This specification updates the usage of the "RELATED-TO"
property defined in Section 3.8.4.5 of <xref target="RFC5545" />
to enable its use with "VALARM" components. Specific types of
relationships between "VALARM" components can be identified by
registering new values for the "RELTYPE" property parameter
defined in Section 3.2.15 of <xref target="RFC5545" />.</t>
<t>The "VALARM" component defined in <xref target="syntax" /> is
extended here as:
<figure>
<artwork name="abnf"><![CDATA[
alarmprop =/ (
; the following is OPTIONAL,
; and MAY occur more than once
related
)
]]></artwork>
</figure></t>
</section>
<section title="Alarm Acknowledgement">
<t>There is currently no way for a "VALARM" component to
indicate whether it has been triggered and acknowledged. With
the advent of a standard client/server protocol for calendaring
and scheduling data (<xref target="RFC4791" />) it is quite
possible for an event with an alarm to exist on multiple clients
in addition to the server. If each of those is responsible for
performing the action when an alarm triggers, then multiple
"alerts" are generated by different devices. In such a
situation, a calendar user would like to be able to "dismiss"
the alarm on one device and have it automatically dismissed on
the others too.</t>
<t>Also, with recurring events that have alarms, it is important
to know when the last alarm in the recurring set was
acknowledged, so that the client can determine whether past
alarms have been missed.</t>
<t>To address these needs, this specification adds an
"ACKNOWLEDGED" property to "VALARM" components to indicate when
the alarm was last acknowledged (or sent, if acknowledgement is
not possible).
This is defined by the
syntax below.
<figure>
<artwork name="abnf"><![CDATA[
alarmprop =/ (
; the following is OPTIONAL,
; but MUST NOT occur more than once
acknowledged
)
]]></artwork>
</figure></t>
<section title="Acknowledged Property" anchor="ACKNOWLEDGED">
<t>
<list style="hanging">
<t hangText="Property Name:">ACKNOWLEDGED</t>
<t hangText="Purpose:">This property specifies the UTC
date and time at which the corresponding alarm was last
sent or acknowledged.</t>
<t hangText="Value Type:">DATE-TIME</t>
<t hangText="Property Parameters:">IANA and non-standard
property parameters can be specified on this property.</t>
<t hangText="Conformance:">This property can be specified
within "VALARM" calendar components.</t>
<t hangText="Description:">This property is used to
specify when an alarm was last sent or acknowledged. This
allows clients to determine when a pending alarm has been
acknowledged by a calendar user so that any alerts can be
dismissed across multiple devices. It also allows clients
to track repeating alarms or alarms on recurring events or
to-dos to ensure that the right number of missed alarms
can be tracked.</t>
<t>Clients SHOULD set this property to the current
date-time value in UTC when a calendar user acknowledges a
pending alarm.
Certain kinds of alarms, such as email-based alerts, might
not provide feedback as to when the calendar user sees them.
For those kinds of alarms, the
client SHOULD set this property when the alarm is
triggered and the action successfully carried out.
<vspace blankLines="1" />When an alarm is triggered on a
client, clients can check to see if an "ACKNOWLEDGED"
property is present. If it is, and the value of that
property is greater than or equal to the computed trigger
time for the alarm, then the client SHOULD NOT trigger the
alarm. Similarly, if an alarm has been triggered and an
"alert" presented to a calendar user, clients can monitor
the iCalendar data to determine whether an "ACKNOWLEDGED" property
is added or changed in the alarm component. If the value
of any "ACKNOWLEDGED" property in the alarm changes and is greater
than or equal to the trigger time of the alarm, then
clients SHOULD dismiss or cancel any "alert" presented to
the calendar user.</t>
<t hangText="Format Definition:">This property is defined
by the following notation:
<figure>
<artwork name="abnf"><![CDATA[
acknowledged = "ACKNOWLEDGED" *acknowledgedparam ":" datetime CRLF
acknowledgedparam = (
; the following is OPTIONAL,
; and MAY occur more than once
(";" other-param)
)
]]></artwork>
</figure></t>
<t hangText="Example:">The following is an example of this property:
<figure>
<artwork><![CDATA[
ACKNOWLEDGED:20090604T084500Z
]]></artwork>
</figure></t>
</list>
</t>
</section>
</section>
<section title="Snoozing Alarms" anchor="snooze">
<t>Users often want to "snooze" an alarm, and this specification
defines a standard approach to accomplish that.</t>
<t>To "snooze" an alarm that has been triggered, clients MUST do
the following:
<list style='numbers'>
<t>Set the "ACKNOWLEDGED" property
(see <xref target="ACKNOWLEDGED"/>) on the triggered alarm.
<vspace blankLines="1"/>
</t>
<t>Create a new "VALARM" component (the "snooze" alarm) within
the parent component of the triggered alarm
(i.e., as a "sibling" component of the triggered alarm).
<list style='letters'>
<t>The new "snooze" alarm MUST be set to trigger
at the user's chosen "snooze" interval after the original alarm
triggered. Clients SHOULD use an absolute "TRIGGER" property
with a "DATE-TIME" value specified in UTC.</t>
<t>The new "snooze" alarm MUST have a "RELATED-TO" property
(see <xref target="RELATED"/>)
with a value set to the "UID" property value of the original
"VALARM" component that was triggered.
If the triggered "VALARM" component does not
already have a "UID" property, the client MUST add one. The
"RELATED-TO" property added to the new "snooze" alarm MUST
include a "RELTYPE" property parameter with a value set to
"SNOOZE" (see <xref target='SNOOZE-PARAM'/>).</t>
</list>
</t>
<t>When the "snooze" alarm is triggered, the client MUST do the
following:
<list style='letters'>
<t>Update the "ACKNOWLEDGED" property on the original related
alarm.</t>
<t>If the "snooze" alarm is itself "snoozed", the client MUST
remove the "snooze" alarm component, and return to step 2.
<vspace blankLines="1"/>
Otherwise, if the "snooze" alarm is dismissed, the client
MUST do one of the following:
<list style="symbols">
<t>Set the "ACKNOWLEDGED" property on the "snooze" alarm.</t>
<t>Remove the "snooze" alarm component.</t>
</list>
</t>
</list>
</t>
</list>
</t>
<!--
<t>To "snooze" an alarm, clients create a new "VALARM" component
within the parent component of the "VALARM" that was triggered
and is being "snoozed" (i.e., as a "sibling" component of the
"VALARM" being snoozed). The new "VALARM" MUST be set to trigger
at the user's chosen "snooze" interval after the original alarm
triggered. Clients SHOULD use an absolute "TRIGGER" property
with a "DATE-TIME" value specified in UTC.</t>
<t>Clients MUST add a
"RELATED-TO" property to the new "VALARM" component with a value
set to the "UID" property value of the "VALARM" component being
snoozed. If the "VALARM" component being snoozed does not
already have a "UID" property, the client MUST add one. The
"RELATED-TO" property added to the new "VALARM" component MUST
include a "RELTYPE" property parameter with a value set to
"SNOOZE".</t>
<t>When the "snooze" alarm is triggered and dismissed the client
MUST do one of the following with the corresponding "VALARM" component:
<list style="symbols">
<t>Set the "ACKNOWLEDGED" property
(see <xref target="ACKNOWLEDGED"/>)</t>
<t>Remove the component</t>
</list>
Alternatively, if the "snooze" alarm
is itself "snoozed", the client MUST remove the original
"snooze" alarm and create a new one, with the appropriate
trigger time and relationship set.</t>
-->
<t>Note that regardless of the final disposition of the "snooze"
alarm when triggered, the original "VALARM" component is left
unchanged other than updating its "ACKNOWLEDGED" property.</t>
<section title="Relationship Type Property Parameter" anchor="SNOOZE-PARAM">
<t>
This specification adds the "SNOOZE" relationship type for
use with the "RELTYPE" property defined in Section 3.2.15
of <xref target="RFC5545" />. This is used when relating a
"snoozed" "VALARM" component to the original alarm that
the "snooze" was generated for.
</t>
</section>
<section title="Example">
<t>The following example shows the snoozing, re-snoozing, and
dismissal of an alarm. Note that the encompassing
VCALENDAR component has been omitted for brevity and that the
line-breaks surrounding the VALARM components are for clarity
only and would not be present in the actual iCalendar data.</t>
<t>Assume that we have the following event with an alarm set
to trigger 15 minutes before the meeting:
<figure>
<artwork><![CDATA[
BEGIN:VEVENT
CREATED:20210302T151004Z
UID:AC67C078-CED3-4BF5-9726-832C3749F627
DTSTAMP:20210302T151004Z
DTSTART;TZID=America/New_York:20210302T103000
DTEND;TZID=America/New_York:20210302T113000
SUMMARY:Meeting
BEGIN:VALARM
UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
TRIGGER:-PT15M
DESCRIPTION:Event reminder
ACTION:DISPLAY
END:VALARM
END:VEVENT
]]></artwork>
</figure>
</t>
<t>When the alarm is triggered, the user decides to snooze it
for 5 minutes. The client acknowledges the original alarm and
creates a new "snooze" alarm as a sibling of, and relates it
to, the original alarm (note that both VALARMs reside within the
same "parent" VEVENT):
<figure>
<artwork><![CDATA[
BEGIN:VEVENT
CREATED:20210302T151004Z
UID:AC67C078-CED3-4BF5-9726-832C3749F627
DTSTAMP:20210302T151516Z
DTSTART;TZID=America/New_York:20210302T103000
DTEND;TZID=America/New_York:20210302T113000
SUMMARY:Meeting
BEGIN:VALARM
UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
TRIGGER:-PT15M
DESCRIPTION:Event reminder
ACTION:DISPLAY
ACKNOWLEDGED:20210302T151514Z
END:VALARM
BEGIN:VALARM
UID:DE7B5C34-83FF-47FE-BE9E-FF41AE6DD097
TRIGGER;VALUE=DATE-TIME:20210302T152000Z
RELATED-TO;RELTYPE=SNOOZE:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
DESCRIPTION:Event reminder
ACTION:DISPLAY
END:VALARM
END:VEVENT
]]></artwork>
</figure>
</t>
<t>When the "snooze" alarm is triggered, the user decides to
snooze it again for an additional 5 minutes. The client
once again acknowledges the original alarm, removes the triggered
"snooze" alarm, and creates another new "snooze" alarm as a
sibling of, and relates it to, the original alarm (note the
different UID for the new snooze alarm):
<figure>
<artwork><![CDATA[
BEGIN:VEVENT
CREATED:20210302T151004Z
UID:AC67C078-CED3-4BF5-9726-832C3749F627
DTSTAMP:20210302T152026Z
DTSTART;TZID=America/New_York:20210302T103000
DTEND;TZID=America/New_York:20210302T113000
SUMMARY:Meeting
BEGIN:VALARM
UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
TRIGGER:-PT15M
DESCRIPTION:Event reminder
ACTION:DISPLAY
ACKNOWLEDGED:20210302T152024Z
END:VALARM
BEGIN:VALARM
UID:87D690A7-B5E8-4EB4-8500-491F50AFE394
TRIGGER;VALUE=DATE-TIME:20210302T152500Z
RELATED-TO;RELTYPE=SNOOZE:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
DESCRIPTION:Event reminder
ACTION:DISPLAY
END:VALARM
END:VEVENT
]]></artwork>
</figure>
</t>
<t>When the second "snooze" alarm is triggered, the user
decides to dismiss it. The client acknowledges both the
original alarm and the second "snooze" alarm:
<figure>
<artwork><![CDATA[
BEGIN:VEVENT
CREATED:20210302T151004Z
UID:AC67C078-CED3-4BF5-9726-832C3749F627
DTSTAMP:20210302T152508Z
DTSTART;TZID=America/New_York:20210302T103000
DTEND;TZID=America/New_York:20210302T113000
SUMMARY:Meeting
BEGIN:VALARM
UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
TRIGGER:-PT15M
DESCRIPTION:Event reminder
ACTION:DISPLAY
ACKNOWLEDGED:20210302T152507Z
END:VALARM
BEGIN:VALARM
UID:87D690A7-B5E8-4EB4-8500-491F50AFE394
TRIGGER;VALUE=DATE-TIME:20210302T152500Z
RELATED-TO;RELTYPE=SNOOZE:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
DESCRIPTION:Event reminder
ACTION:DISPLAY
ACKNOWLEDGED:20210302T152507Z
END:VALARM
END:VEVENT
]]></artwork>
</figure>
</t>
</section>
</section>
<section title="Alarm Proximity Trigger" anchor="proximity">
<t>VALARMs are currently triggered when a specific date-time is
reached. It is also desirable to be able to trigger alarms based
on location, e.g. when arriving at or departing from a
particular location.</t>
<t>This specification adds the following elements to "VALARM"
components to indicate when an alarm can be triggered based on
location.
<list>
<t>"PROXIMITY" property - indicates that a location based trigger is to
be used and which action is used for the trigger</t>
<t><xref target="I-D.ietf-calext-eventpub-extensions">
"VLOCATION" component(s)</xref> - used to indicate the actual
location(s) to trigger off of, specified with a URL property containing a
<xref target="RFC5870">geo: URI</xref> which allows for two or three
coordinate values with an optional uncertainty</t>
</list>
<figure>
<artwork name="abnf"><![CDATA[
alarmprop =/ (
; the following is OPTIONAL,
; but MUST NOT occur more than once
proximity /
)
alarm-subcomp =/ (
; the following is OPTIONAL,
; and MAY occur more than once, but only
; when a PROXIMITY property is also present
locationc
)
]]></artwork>
</figure></t>
<t>
Typically, when a "PROXIMITY" property is used there is no
need to specify a time-based trigger using the "TRIGGER"
property. However, since "TRIGGER" is defined as a required
property for a "VALARM" component, for backwards compatibility
it has to be present, but ignored. To indicate a "TRIGGER"
that is to be ignored, clients SHOULD use a value a long time
in the past. A value of "19760401T005545Z" has been commonly
used for this purpose.
</t>
<section title="Proximity Property" anchor="PROXIMITY">
<t>
<list style="hanging">
<t hangText="Property Name:">PROXIMITY</t>
<t hangText="Purpose:">This property indicates that a
location based trigger is applied to an alarm.</t>
<t hangText="Value Type:">TEXT</t>
<t hangText="Property Parameters:">IANA and non-standard
property parameters can be specified on this property.</t>
<t hangText="Conformance:">This property can be specified
within "VALARM" calendar components.</t>
<t hangText="Description:">This property is used to
indicate that an alarm has a location-based trigger.
Its value identifies the action that will trigger the alarm.</t>
<t>When the property value is set to "ARRIVE", the alarm
is triggered when the calendar user agent arrives in the
vicinity of one or more locations. When set to
"DEPART", the alarm is triggered when the calendar user
agent departs from the vicinity of one or more locations.
Each location which MUST be specified with a "VLOCATION"
component.
Note that the meaning of "vicinity" in this
context is implementation defined.</t>
<t>When the property value is set to "CONNECT", the alarm
is triggered when the calendar user agent connects to a
automobile to which is has been paired via
<xref target="BTcore">Bluetooth(R)</xref>.
When set to "DISCONNECT", the alarm is
triggered when the calendar user agent disconnects from a
automobile to which it has been paired via Bluetooth(R).
Note that neither current implementations of proximty
alarms nor this document have a mechanism to target a
particular automobile.
Such a mechanism may be specified in a future extension.</t>
<t hangText="Format Definition:">This property is defined
by the following notation:
<figure>
<artwork name="abnf"><![CDATA[
proximity = "PROXIMITY" *proximityparam ":" proximityvalue CRLF
proximityparam = (
; the following is OPTIONAL,
; and MAY occur more than once
(";" other-param)
)
proximityvalue = "ARRIVE" / "DEPART" /
"CONNECT" / "DISCONNECT" / iana-token / x-name
]]></artwork>
</figure></t>
</list>
</t>
</section>
<section title="Example">
<t>The following example shows a VALARM component with a
proximity trigger set to trigger when the device running the
calendar user agent leaves the vicinity defined by the
URL property in the VLOCATION component. Note use of the "u=" parameter
with the "geo" URI to define the uncertainty of the location
determination.
<figure>
<artwork name="abnf"><![CDATA[
BEGIN:VALARM
UID:77D80D14-906B-4257-963F-85B1E734DBB6
ACTION:DISPLAY
TRIGGER;VALUE=DATE-TIME:19760401T005545Z
DESCRIPTION:Remember to buy milk
PROXIMITY:DEPART
BEGIN:VLOCATION
UID:123456-abcdef-98765432
NAME:Office
URL:geo:40.443,-79.945;u=10
END:VLOCATION
END:VALARM
]]></artwork>
</figure></t>
</section>
</section>
<section title='Security Considerations'>
<t>In addition to the security properties of iCalendar
(see Section 7 of <xref target="RFC5545"/>),
VALARMs, if not monitored properly, can be used to disturb
users and/or leak personal information. For instance, an
undesirable audio alert could cause embarassment. An
unwanted display alert could be considered an annoyance. Or an
email alert could be used to leak a user's location to a third
party or to send unsolicited email to multiple users.
Therefore, CalDAV clients and servers that accept iCalendar data
from a third party (e.g. via <xref target="RFC5546">iTIP</xref>,
a subscription feed, or a shared calendar) SHOULD remove all
VALARMs from the data prior to storing in their calendar system.</t>
<t>Security considerations related to unique identifiers for VALARMs
are discussed in <xref target='uid'/>.</t>
</section>
<section title='Privacy Considerations'>
<t>Proximity VALARMs, if not used carefully, can leak a
user's past, present, or future location. For instance,
storing an iCalendar resource containing proxmity VALARMs to a
shared calendar on CalDAV server can expose to anyone that has
access to that calendar the user's intent to leave
from or arrive at a particular location at some future time.
Furthermore, if a CalDAV client updates the shared iCalendar
resource with an ACKNOWLEDGED property when the alarm is
triggered, will leak the exact date and time that the user left
from or arrived at the location.
Therefore, CalDAV clients that implement proximity alarms
SHOULD give users the option of storing and/or acknowledging the
alarms on the local device only and not storing the alarm and/or
acknowledgment on a remote server.</t>
<t>Privacy considerations related to unique identifiers for VALARMs
are discussed in <xref target='uid'/>.</t>
</section>
<section title='IANA Considerations'>
<section title='Property Registrations'>
<t>This document defines the following new iCalendar
properties to be added to the registry defined in Section
8.2.3 of <xref target="RFC5545" /> and located here:
<eref target="https://www.iana.org/assignments/icalendar#properties"/>
</t>
<texttable>
<ttcol>Property</ttcol>
<ttcol>Status</ttcol>
<ttcol>Reference</ttcol>
<c>ACKNOWLEDGED</c>
<c>Current</c>
<c>RFCXXXX, <xref target="ACKNOWLEDGED" /></c>
<c>PROXIMITY</c>
<c>Current</c>
<c>RFCXXXX, <xref target="PROXIMITY" /></c>
</texttable>
</section>
<section title='Relationship Types Registry'>
<t>This document defines the following new iCalendar
relationship type to be added to the registry defined in
Section 8.3.8 of <xref target="RFC5545" /> and located here:
<eref target="https://www.iana.org/assignments/icalendar#relationship-types"/>
</t>
<texttable>
<ttcol>Relationship Type</ttcol>
<ttcol>Status</ttcol>
<ttcol>Reference</ttcol>
<c>SNOOZE</c>
<c>Current</c>
<c>RFCXXXX, <xref target="SNOOZE-PARAM" /></c>
</texttable>
</section>
<section title="Proximity Value Registry">
<t>This document creates a new iCalendar registry for values
of the "PROXIMITY" property located here:
<eref target="https://www.iana.org/assignments/icalendar#proximity-values"/></t>
<t>Additional values MAY be used, provided the process described in
Section 8.2.1 of <xref target="RFC5545"/> is used to
register them, using the template in Section 8.2.6 of
<xref target="RFC5545"/>.
</t>
<t>The following table has been used to initialize the
Proximity Value Registry.</t>
<texttable>
<ttcol>Value</ttcol>
<ttcol>Status</ttcol>
<ttcol>Reference</ttcol>
<c>ARRIVE</c>
<c>Current</c>
<c>RFCXXXX, <xref target="PROXIMITY" /></c>
<c>DEPART</c>
<c>Current</c>
<c>RFCXXXX, <xref target="PROXIMITY" /></c>
<c>CONNECT</c>
<c>Current</c>
<c>RFCXXXX, <xref target="PROXIMITY" /></c>
<c>DISCONNECT</c>
<c>Current</c>
<c>RFCXXXX, <xref target="PROXIMITY" /></c>
</texttable>
</section>
</section>
<section title='Acknowledgments'>
<t>This specification came about via discussions at the
Calendaring and Scheduling Consortium. Also, thanks to the
following for providing feedback: Bernard Desruisseaux, Mike
Douglass, Jacob Farkas, Jeffrey Harris, Ciny Joy, Barry Leiba,
and Daniel Migault.</t>
</section>
</middle>
<back>
<references title='Normative References'>
&rfc2119;
&rfc5545;
&rfc5870;
&rfc7986;
&rfc8174;
&idEventPub;
</references>
<references title='Informative References'>
&rfc4791;
&rfc5546;
<reference anchor="BTcore"
target="https://www.bluetooth.com/specifications/bluetooth-core-specification">
<front>
<title>Bluetooth Core Specification Version 5.0</title>
<author>
<organization>Bluetooth Special Interest Group</organization>
</author>
<date month="December" year="2016"/>
</front>
<format type="HTML"
target="https://www.bluetooth.com/specifications/bluetooth-core-specification"/>
</reference>
</references>
<section title="Change History (To be removed by RFC Editor before
publication)">
<t>Changes in ietf-06:
<list style='numbers'>
<t>Corrected timestamps in snooze example.</t>
<t>Editorial changes from Benjamim Kaduk.</t>
</list></t>
<t>Changes in ietf-05:
<list style='numbers'>
<t>Updated to use VLOCATION components rather than
(deprecated) STRUCTURED-LOCATION properties for proximity
alarms.</t>
<t>Reorganized and clarified the process of snoozing an alarm
and added an example.</t>
<t>Noted that there is currently no mechanism for specifying
a particular automobile for CONNECT/DISCONNECT proximity alarms.</t>
<t>Replaced the term "spam" with new wording in Security
Considerations.</t>
<t>Addressed IESG comments from Benjamim Kaduk.</t>
<t>Addressed IESG comments from Robert Wilton.</t>
<t>Addressed IESG comments Alissa Cooper.</t>
</list></t>
<t>Changes in ietf-04:
<list style='numbers'>
<t>Addressed security review comments from Valery Smyslov.</t>
<t>Addressed Genart review comments from Roni Even.</t>
<t>Added text addressing management of Proximity Value Registry.</t>
</list></t>
<t>Changes in ietf-03:
<list style='numbers'>
<t>Fixed ABNF to be properly extended.</t>
<t>Addressed AD review comments from Barry Leiba.</t>
</list></t>
<t>Changes in ietf-02:
<list style='numbers'>
<t>Addressed some WGLC comments from Daniel Migault.</t>
</list></t>
<t>Changes in ietf-01:
<list style='numbers'>
<t>Reintroduced the RELATED-TO property for VALARMs
and the SNOOZE value for the RELTYPE property parameter.</t>
<t>Add Privacy Considerations section.</t>
</list></t>
<t>Changes in ietf-00:
<list style='numbers'>
<t>Submitted as CALEXT draft.</t>
</list></t>
<t>Changes in daboo-05:
<list style='numbers'>
<t>Added Murchison as editor.</t>
<t>Updated keywords boilerplate.</t>
<t>Added reference to UID security/privacy recommendations.</t>
<t>Removed default alarms.</t>
<t>Removed ALARM-AGENT property.</t>
<t>Added text about using TRIGGER value in the past in
addition to ACTION:NONE to have a default alarm be
ignored.</t>
<t>Removed text about related alarms.</t>
<t>Removed URL alarm action.</t>
<t>Added reference to draft-ietf-calext-eventpub-extensions
for STRUCTURED-LOCATION.</t>
<t>Added CONNECT and DISCONNECT PROXIMITY property values.</t>
<t>Added Security Considerations.</t>
<t>Editorial fixes.</t>
</list></t>
<t>Changes in daboo-04:
<list style='numbers'>
<t>Changed "ID" to "AGENT-ID".</t>
<t>Add more text on using "ACKNOWLEDGED" property.</t>
<t>Add "RELATED-TO" as a valid property for VALARMs.</t>
<t>Add "SNOOZE" relationship type for use with VALARMs.</t>
<t>State that "TRIGGER" is typically ignored in proximity alarms.</t>
<t>Added "PROXIMITY" value registry.</t>
<t>Added a lot more detail on default alarms including new
action and property.</t>