Create a private operator= so compiler doesn't generate an unsafe one. Only Incidence...
[extendedkcal:kdab-developers-kcalsplit.git] / kcalcore / src / incidence.h
1 /*
2   This file is part of the kcalcore library.
3
4   Copyright (c) 2001-2003 Cornelius Schumacher <schumacher@kde.org>
5   Copyright (C) 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com>
6
7   This library is free software; you can redistribute it and/or
8   modify it under the terms of the GNU Library General Public
9   License as published by the Free Software Foundation; either
10   version 2 of the License, or (at your option) any later version.
11
12   This library is distributed in the hope that it will be useful,
13   but WITHOUT ANY WARRANTY; without even the implied warranty of
14   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15   Library General Public License for more details.
16
17   You should have received a copy of the GNU Library General Public License
18   along with this library; see the file COPYING.LIB.  If not, write to
19   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20   Boston, MA 02110-1301, USA.
21 */
22 /**
23   @file
24   This file is part of the API for handling calendar data and
25   defines the Incidence class.
26
27   @author Cornelius Schumacher \<schumacher@kde.org\>
28   @author Reinhold Kainhofer \<reinhold@kainhofer.com\>
29 */
30
31 #ifndef INCIDENCE_H
32 #define INCIDENCE_H
33
34 #include "kcalcore_export.h"
35 #include "alarm.h"
36 #include "attachment.h"
37 #include "incidencebase.h"
38 #include "recurrence.h"
39
40 //@cond PRIVATE
41 // Value used to signal invalid/unset latitude or longitude.
42 #define INVALID_LATLON 255.0
43 //@endcond
44
45 namespace KCalCore {
46
47 /**
48   @brief
49   Provides the abstract base class common to non-FreeBusy (Events, To-dos,
50   Journals) calendar components known as incidences.
51
52   Several properties are not allowed for VFREEBUSY objects (see rfc:2445),
53   so they are not in IncidenceBase. The hierarchy is:
54
55   IncidenceBase
56   + FreeBusy
57   + Incidence
58     + Event
59     + Todo
60     + Journal
61
62   So IncidenceBase contains all properties that are common to all classes,
63   and Incidence contains all additional properties that are common to
64   Events, Todos and Journals, but are not allowed for FreeBusy entries.
65 */
66 class KCALCORE_EXPORT Incidence
67   : public IncidenceBase, public Recurrence::RecurrenceObserver
68 {
69   public:
70
71     /**
72       The different types of overall incidence status or confirmation.
73       The meaning is specific to the incidence type in context.
74     */
75     enum Status {
76       StatusNone,           /**< No status */
77       StatusTentative,      /**< event is tentative */
78       StatusConfirmed,      /**< event is definite */
79       StatusCompleted,      /**< to-do completed */
80       StatusNeedsAction,    /**< to-do needs action */
81       StatusCanceled,       /**< event or to-do canceled; journal removed */
82       StatusInProcess,      /**< to-do in process */
83       StatusDraft,          /**< journal is draft */
84       StatusFinal,          /**< journal is final */
85       StatusX               /**< a non-standard status string */
86     };
87
88     /**
89       The different types of incidence access classifications.
90     */
91     enum Secrecy {
92       SecrecyPublic,      /**< Not secret (default) */
93       SecrecyPrivate,     /**< Secret to the owner */
94       SecrecyConfidential /**< Secret to the owner and some others */
95     };
96
97     /**
98        The different types of RELTYPE values specified by the RFC.
99        Only RelTypeParent is supported for now.
100     */
101     enum RelType {
102       RelTypeParent,  /**< The related incidence is a parent. */
103       RelTypeChild,   /**< The related incidence is a child. */
104       RelTypeSibling, /**< The related incidence is a peer. */
105     };
106
107     /**
108       A shared pointer to an Incidence.
109     */
110     typedef QSharedPointer<Incidence> Ptr;
111
112     /**
113       A shared pointer to a non-mutable Incidence.
114     */
115     typedef QSharedPointer<const Incidence> ConstPtr;
116
117     /**
118       List of incidences.
119     */
120     typedef QList<Ptr> List;
121
122     /**
123       Constructs an empty incidence.*
124     */
125     Incidence();
126
127     /**
128       Copy constructor.
129       @param other is the incidence to copy.
130     */
131     Incidence( const Incidence &other );
132
133     /**
134       Destroys an incidence.
135     */
136     virtual ~Incidence();
137
138     /**
139       Returns an exact copy of this incidence. The returned object is owned
140       by the caller.
141     */
142     virtual Incidence *clone() const = 0;
143
144     /**
145       Set readonly state of incidence.
146
147       @param readonly If true, the incidence is set to readonly, if false the
148                       incidence is set to readwrite.
149     */
150     void setReadOnly( bool readonly );
151
152     /**
153       @copydoc
154       IncidenceBase::setLastModified().
155     */
156     void setLastModified( const KDateTime &lm );
157
158     /**
159       Set localOnly state of incidence.
160       A local only incidence can be updated but it will not increase the revision
161       number neither the modified date.
162
163       @param localonly If true, the incidence is set to localonly, if false the
164                       incidence is set to normal stat.
165     */
166     void setLocalOnly( bool localonly );
167
168     /**
169       Get the localOnly status.
170
171       @see setLocalOnly()
172       @return True if Local only, false otherwise
173     */
174     bool localOnly() const;
175
176     /**
177       @copydoc
178       IncidenceBase::setAllDay().
179     */
180     void setAllDay( bool allDay );
181
182     /**
183       Recreate incidence. The incidence is made a new unique incidence, but already stored
184       information is preserved. Sets unique id, creation date, last
185       modification date and revision number.
186     */
187     void recreate();
188
189     /**
190       Sets the incidence creation date/time. It is stored as a UTC date/time.
191
192       @param dt is the creation date/time.
193       @see created().
194     */
195     void setCreated( const KDateTime &dt );
196
197     /**
198       Returns the incidence creation date/time.
199       @see setCreated().
200     */
201     KDateTime created() const;
202
203     /**
204       Sets the number of revisions this incidence has seen.
205
206       @param rev is the incidence revision number.
207       @see revision().
208     */
209     void setRevision( int rev );
210
211     /**
212       Returns the number of revisions this incidence has seen.
213       @see setRevision().
214     */
215     int revision() const;
216
217     /**
218       Sets the incidence starting date/time.
219
220       @param dt is the starting date/time.
221       @see IncidenceBase::dtStart().
222     */
223     virtual void setDtStart( const KDateTime &dt );
224
225     /**
226       @copydoc
227       IncidenceBase::shiftTimes()
228     */
229     virtual void shiftTimes( const KDateTime::Spec &oldSpec,
230                              const KDateTime::Spec &newSpec );
231
232     /**
233       Sets the incidence description.
234
235       @param description is the incidence description string.
236       @param isRich if true indicates the description string contains richtext.
237       @see description().
238     */
239     void setDescription( const QString &description, bool isRich );
240
241     /**
242       Sets the incidence description and tries to guess if the description
243       is rich text.
244
245       @param description is the incidence description string.
246       @see description().
247       @since 4.1
248     */
249     void setDescription( const QString &description );
250
251     /**
252       Returns the incidence description.
253       @see setDescription().
254       @see richDescription().
255     */
256     QString description() const;
257
258     /**
259       Returns the incidence description in rich text format.
260       @see setDescription().
261       @see description().
262       @since 4.1
263     */
264     QString richDescription() const;
265
266     /**
267       Returns true if incidence description contains RichText; false otherwise.
268       @see setDescription(), description().
269     */
270     bool descriptionIsRich() const;
271
272     /**
273       Sets the incidence summary.
274
275       @param summary is the incidence summary string.
276       @param isRich if true indicates the summary string contains richtext.
277       @see summary().
278     */
279     void setSummary( const QString &summary, bool isRich );
280
281     /**
282       Sets the incidence summary and tries to guess if the summary is richtext.
283
284       @param summary is the incidence summary string.
285       @see summary().
286       @since 4.1
287     */
288     void setSummary( const QString &summary );
289
290     /**
291       Returns the incidence summary.
292       @see setSummary().
293       @see richSummary().
294     */
295     QString summary() const;
296
297     /**
298       Returns the incidence summary in rich text format.
299       @see setSummary().
300       @see summary().
301       @since 4.1
302     */
303     QString richSummary() const;
304
305     /**
306       Returns true if incidence summary contains RichText; false otherwise.
307       @see setSummary(), summary().
308     */
309     bool summaryIsRich() const;
310
311     /**
312       Sets the incidence location. Do _not_ use with journals.
313
314       @param location is the incidence location string.
315       @param isRich if true indicates the location string contains richtext.
316       @see location().
317     */
318     void setLocation( const QString &location, bool isRich );
319
320     /**
321       Sets the incidence location and tries to guess if the location is
322       richtext. Do _not_ use with journals.
323
324       @param location is the incidence location string.
325       @see location().
326       @since 4.1
327     */
328     void setLocation( const QString &location );
329
330     /**
331       Returns the incidence location. Do _not_ use with journals.
332       @see setLocation().
333       @see richLocation().
334     */
335     QString location() const;
336
337     /**
338       Returns the incidence location in rich text format.
339       @see setLocation().
340       @see location().
341       @since 4.1
342     */
343     QString richLocation() const;
344
345     /**
346       Returns true if incidence location contains RichText; false otherwise.
347       @see setLocation(), location().
348     */
349     bool locationIsRich() const;
350
351     /**
352       Sets the incidence category list.
353
354       @param categories is a list of category strings.
355       @see setCategories( const QString &), categories().
356     */
357     void setCategories( const QStringList &categories );
358
359     /**
360       Sets the incidence category list based on a comma delimited string.
361
362       @param catStr is a QString containing a list of categories which
363       are delimited by a comma character.
364       @see setCategories( const QStringList &), categories().
365     */
366     void setCategories( const QString &catStr );
367
368     /**
369       Returns the incidence categories as a list of strings.
370       @see setCategories( const QStringList &), setCategories( Const QString &).
371     */
372     QStringList categories() const;
373
374     /**
375       Returns the incidence categories as a comma separated string.
376       @see categories().
377     */
378     QString categoriesStr() const;
379
380     /**
381       Relates another incidence to this one, by UID. This function should only
382       be used when constructing a calendar before the related incidence exists.
383
384       @param uid is a QString containing a UID for another incidence.
385       @param relType specifies the relation type.
386
387       @warning KCalCore only supports one related-to field per reltype for now.
388
389       @see relatedTo().
390     */
391     void setRelatedTo( const QString &uid, RelType relType = RelTypeParent );
392
393     /**
394       Returns a UID string for the incidence that is related to this one.
395       This function should only be used when constructing a calendar before
396       the related incidence exists.
397
398       @warning KCalCore only supports one related-to field per reltype for now.
399
400       @param relType specifies the relation type.
401
402       @see setRelatedTo().
403     */
404     QString relatedTo( RelType relType = RelTypeParent ) const;
405
406 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
407 // %%%%%  Convenience wrappers for property handling
408 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
409     /**
410        Returns true if the alternative (=text/html) description is
411        available.
412        @see setAltDescription(), altDescription()
413     */
414     bool hasAltDescription() const;
415     /**
416       Sets the incidence's alternative (=text/html) description. If
417       the text is empty, the property is removed.
418
419       @param altdescription is the incidence altdescription string.
420       @see altAltdescription().
421     */
422     void setAltDescription( const QString &altdescription );
423
424     /**
425       Returns the incidence alternative (=text/html) description.
426       @see setAltDescription().
427     */
428     QString altDescription() const;
429
430 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
431 // %%%%%  Recurrence-related methods
432 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
433
434     /**
435       Returns the recurrence rule associated with this incidence. If there is
436       none, returns an appropriate (non-0) object.
437     */
438     Recurrence *recurrence() const;
439
440     /**
441       Removes all recurrence and exception rules and dates.
442     */
443     void clearRecurrence();
444
445     /**
446       @copydoc
447       Recurrence::recurs()
448     */
449     bool recurs() const;
450
451     /**
452       @copydoc
453       Recurrence::recurrenceType()
454     */
455     ushort recurrenceType() const;
456
457     /**
458       @copydoc
459       Recurrence::recursOn()
460     */
461     virtual bool recursOn( const QDate &date, const KDateTime::Spec &timeSpec ) const;
462
463     /**
464       @copydoc
465       Recurrence::recursAt()
466     */
467     bool recursAt( const KDateTime &dt ) const;
468
469     /**
470       Calculates the start date/time for all recurrences that happen at some
471       time on the given date (might start before that date, but end on or
472       after the given date).
473
474       @param date the date when the incidence should occur
475       @param timeSpec time specification for @p date.
476       @return the start date/time of all occurrences that overlap with the
477       given date; an empty list if the incidence does not overlap with the
478       date at all.
479     */
480     virtual QList<KDateTime> startDateTimesForDate(
481       const QDate &date,
482       const KDateTime::Spec &timeSpec = KDateTime::LocalZone ) const;
483
484     /**
485       Calculates the start date/time for all recurrences that happen at the
486       given time.
487
488       @param datetime the date/time when the incidence should occur.
489       @return the start date/time of all occurrences that overlap with the
490       given date/time; an empty list if the incidence does not happen at the
491       given time at all.
492     */
493     virtual QList<KDateTime> startDateTimesForDateTime(
494       const KDateTime &datetime ) const;
495
496     /**
497       Returns the end date/time of the incidence occurrence if it starts at
498       specified date/time.
499
500       @param startDt is the specified starting date/time.
501       @return the corresponding end date/time for the occurrence; or the start
502       date/time if the end date/time is invalid; or the end date/time if
503       the start date/time is invalid.
504     */
505     virtual KDateTime endDateForStart( const KDateTime &startDt ) const;
506
507 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
508 // %%%%%  Attachment-related methods
509 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
510
511     /**
512       Adds an attachment to the incidence.
513
514       @param attachment is a pointer to a valid Attachment object.
515       @see deleteAttachment().
516     */
517     void addAttachment( const Attachment::Ptr &attachment );
518
519     /**
520       Removes the specified attachment from the incidence.  Additionally,
521       the memory used by the attachment is freed.
522
523       @param attachment is a pointer to a valid Attachment object.
524       @see addAttachment(), deleteAttachments().
525     */
526     void deleteAttachment( const Attachment::Ptr &attachment );
527
528     /**
529       Removes all attachments of the specified MIME type from the incidence.
530       The memory used by all the removed attachments is freed.
531
532       @param mime is a QString containing the MIME type.
533       @see deleteAttachment().
534     */
535     void deleteAttachments( const QString &mime );
536
537     /**
538       Returns a list of all incidence attachments.
539       @see attachments( const QString &).
540     */
541     Attachment::List attachments() const;
542
543     /**
544       Returns a list of all incidence attachments with the specified MIME type.
545
546       @param mime is a QString containing the MIME type.
547       @see attachments().
548     */
549     Attachment::List attachments( const QString &mime ) const;
550
551     /**
552       Removes all attachments and frees the memory used by them.
553       @see deleteAttachment( Attachment::Ptr), deleteAttachments( const QString &).
554     */
555     void clearAttachments();
556
557     /**
558       Writes the data in the attachment @p attachment to a temporary file
559       and returns the local name of the temporary file.
560
561       @param attachment is a pointer to a valid Attachment instance.
562       @return a string containing the name of the temporary file containing the attachment.
563       @see clearTempFiles().
564     */
565     QString writeAttachmentToTempFile( const Attachment::Ptr &attachment ) const;
566
567     /**
568       Deletes all temporary files used by attachments and frees any memory in use by them.
569       @see writeAttachmentToTempFile().
570     */
571     void clearTempFiles();
572
573 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
574 // %%%%%  Secrecy and Status methods
575 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
576
577     /**
578       Sets the incidence #Secrecy.
579
580       @param secrecy is the incidence #Secrecy to set.
581       @see secrecy(), secrecyStr().
582     */
583     void setSecrecy( Secrecy secrecy );
584
585     /**
586       Returns the incidence #Secrecy.
587       @see setSecrecy(), secrecyStr().
588     */
589     Secrecy secrecy() const;
590
591     /**
592       Sets the incidence status to a standard #Status value.
593       Note that StatusX cannot be specified.
594
595       @param status is the incidence #Status to set.
596       @see status(), setCustomStatus().
597     */
598     void setStatus( Status status );
599
600     /**
601       Sets the incidence #Status to a non-standard status value.
602
603       @param status is a non-standard status string. If empty,
604       the incidence #Status will be set to StatusNone.
605       @see setStatus(), status() customStatus().
606     */
607     void setCustomStatus( const QString &status );
608
609     /**
610        Returns the non-standard status value.
611        @see setCustomStatus().
612     */
613     QString customStatus() const;
614
615     /**
616       Returns the incidence #Status.
617       @see setStatus(), setCustomStatus(), statusStr().
618     */
619     Status status() const;
620
621 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
622 // %%%%%  Other methods
623 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
624
625     /**
626       Sets a list of incidence resources. (Note: resources in this context
627       means items used by the incidence such as money, fuel, hours, etc).
628
629       @param resources is a list of resource strings.
630       @see resources().
631     */
632     void setResources( const QStringList &resources );
633
634     /**
635       Returns the incidence resources as a list of strings.
636       @see setResources().
637     */
638     QStringList resources() const;
639
640     /**
641       Sets the incidences priority. The priority must be an integer value
642       between 0 and 9, where 0 is undefined, 1 is the highest, and 9 is the
643       lowest priority (decreasing order).
644
645       @param priority is the incidence priority to set.
646       @see priority().
647     */
648     void setPriority( int priority );
649
650     /**
651       Returns the incidence priority.
652       @see setPriority().
653     */
654     int priority() const;
655
656     /**
657       Returns true if the incidence has geo data, otherwise return false.
658       @see setHasGeo(), setGeoLatitude(float), setGeoLongitude(float).
659       @since 4.3
660     */
661     bool hasGeo() const;
662
663     /**
664       Sets if the incidence has geo data.
665       @param hasGeo true if incidence has geo data, otherwise false
666       @see hasGeo(), geoLatitude(), geoLongitude().
667       @since 4.3
668     */
669     void setHasGeo( bool hasGeo );
670
671     /**
672       Set the incidences geoLatitude.
673       @param geolatitude is the incidence geolatitude to set
674       @see geoLatitude().
675       @since 4.3
676     */
677     void setGeoLatitude( float geolatitude );
678
679     /**
680       Returns the incidence geoLatidude.
681       @return incidences geolatitude value
682       @see setGeoLatitude().
683       @since 4.3
684     */
685     float geoLatitude() const;
686
687     /**
688       Set the incidencesgeoLongitude.
689       @param geolongitude is the incidence geolongitude to set
690       @see geoLongitude().
691       @since 4.3
692     */
693     void setGeoLongitude( float geolongitude );
694
695     /**
696       Returns the incidence geoLongitude.
697       @return incidences geolongitude value
698       @see setGeoLongitude().
699       @since 4.3
700     */
701     float geoLongitude() const;
702
703     /**
704       Returns true if the incidence has recurrenceId, otherwise return false.
705       @see setHasRecurrenceID(), setRecurrenceId(KDateTime)
706       @since 4.3
707     */
708     bool hasRecurrenceId() const;
709
710     /**
711       Set the incidences recurrenceId.
712       @param recurrenceId is the incidence recurrenceId to set
713       @see recurrenceId().
714       @since 4.3
715     */
716     void setRecurrenceId( const KDateTime &recurrenceId );
717
718     /**
719       Returns the incidence recurrenceId.
720       @return incidences recurrenceId value
721       @see setRecurrenceId().
722       @since 4.3
723     */
724     KDateTime recurrenceId() const;
725
726 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
727 // %%%%%  Alarm-related methods
728 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
729
730     /**
731       Returns a list of all incidence alarms.
732     */
733     Alarm::List alarms() const;
734
735     /**
736       Create a new incidence alarm.
737     */
738     Alarm::Ptr newAlarm();
739
740     /**
741       Adds an alarm to the incidence.
742
743       @param alarm is a pointer to a valid Alarm object.
744       @see removeAlarm().
745     */
746     void addAlarm( const Alarm::Ptr &alarm );
747
748     /**
749       Removes the specified alarm from the incidence.
750
751       @param alarm is a pointer to a valid Alarm object.
752       @see addAlarm().
753     */
754     void removeAlarm( const Alarm::Ptr &alarm );
755
756     /**
757       Removes all alarms.
758       @see removeAlarm().
759     */
760     void clearAlarms();
761
762     /**
763       Returns true if any of the incidence alarms are enabled; false otherwise.
764     */
765     bool isAlarmEnabled() const;
766
767 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
768 // %%%%%  Other methods
769 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
770
771     /**
772       Set the incidence scheduling ID. Do _not_ use with journals.
773       This is used for accepted invitations as the place to store the UID
774       of the invitation. It is later used again if updates to the
775       invitation comes in.
776       If we did not set a new UID on incidences from invitations, we can
777       end up with more than one resource having events with the same UID,
778       if you have access to other peoples resources.
779
780       @param sid is a QString containing the scheduling ID.
781       @see schedulingID().
782     */
783     void setSchedulingID( const QString &sid );
784
785     /**
786       Returns the incidence scheduling ID. Do _not_ use with journals.
787       If a scheduling ID is not set, then return the incidence UID.
788       @see setSchedulingID().
789     */
790     QString schedulingID() const;
791
792     /**
793       Observer interface for the recurrence class. If the recurrence is
794       changed, this method will be called for the incidence the recurrence
795       object belongs to.
796
797       @param recurrence is a pointer to a valid Recurrence object.
798     */
799     virtual void recurrenceUpdated( Recurrence *recurrence );
800
801   protected:
802     /**
803       Compares this with Incidence @p incidence for equality.
804       @param incidence is the Incidence to compare against.
805       @return true if the incidences are equal; false otherwise.
806     */
807     virtual bool equals( const IncidenceBase &incidence ) const;
808
809     /**
810       @copydoc
811       IncidenceBase::assign()
812     */
813     virtual IncidenceBase &assign( const IncidenceBase &other );
814
815   private:
816     /**
817        Disabled, not polymorphic.
818        Use IncidenceBase::operator= which is safe because it calls
819        virtual function assign.
820      */
821     Incidence &operator=( const Incidence &other );
822
823     //@cond PRIVATE
824     class Private;
825     Private *const d;
826     //@endcond
827 };
828
829 }
830
831 //@cond PRIVATE
832 inline uint qHash( const QSharedPointer<KCalCore::Incidence> &key )
833 {
834   return qHash<KCalCore::Incidence>( key.data() );
835 }
836 //@endcond
837
838 #endif