KAlarmCal

kacalendar.h
1 /*
2  * kacalendar.h - KAlarm kcal library calendar and event categorisation
3  * This file is part of kalarmcal library, which provides access to KAlarm
4  * calendar data.
5  * SPDX-FileCopyrightText: 2005-2020 David Jarvie <[email protected]>
6  *
7  * SPDX-License-Identifier: LGPL-2.0-or-later
8  */
9 
10 #pragma once
11 
12 #include "kalarmcal_export.h"
13 
14 #include <KCalendarCore/FileStorage>
15 #include <KCalendarCore/Calendar>
16 #include <KCalendarCore/Event>
17 
18 #include <Akonadi/Collection>
19 
20 #include <QByteArray>
21 #include <QStringList>
22 #include <QDebug>
23 
24 namespace KCalendarCore
25 {
26 class Alarm;
27 }
28 
29 namespace KAlarmCal
30 {
31 
32 extern const QLatin1String KALARMCAL_EXPORT MIME_BASE; //!< The base mime type for KAlarm alarms
33 extern const QLatin1String KALARMCAL_EXPORT MIME_ACTIVE; //!< The mime type for KAlarm active alarms
34 extern const QLatin1String KALARMCAL_EXPORT MIME_ARCHIVED; //!< The mime type for KAlarm archived alarms
35 extern const QLatin1String KALARMCAL_EXPORT MIME_TEMPLATE; //!< The mime type for KAlarm alarm templates
36 
37 /** Declaration type for a calendar resource ID. */
38 using ResourceId = Akonadi::Collection::Id;
39 
40 /**
41  * @short Class representing attributes of a KAlarm calendar.
42  *
43  * KACalendar provides methods to check and convert the KAlarm calendar format
44  * version, and to get and set the iCalendar product ID (which contains the
45  * identity of the application which wrote the calendar).
46  *
47  * @author David Jarvie <[email protected]>
48  */
49 namespace KACalendar
50 {
51 /** Compatibility of resource backend calendar format. */
53  Unknown = 0, //!< format not determined
54  Current = 0x02, //!< in current KAlarm format
55  Converted = Current | 0x01, //!< in current KAlarm format, but not yet saved
56  Convertible = 0x04, //!< in an older KAlarm format
57  Incompatible = 0x08 //!< not written by KAlarm, or in a newer KAlarm version
58 };
59 Q_DECLARE_FLAGS(Compat, Compatibility)
60 
61 /** Special calendar storage format version codes.
62  * Positive version values are actual KAlarm format version numbers.
63  */
64 enum {
65  CurrentFormat = 0, //!< current KAlarm format
66  MixedFormat = -2, //!< calendar may contain more than one version
67  IncompatibleFormat = -1 //!< not written by KAlarm, or a newer KAlarm version
68 };
69 
70 /** Check the version of KAlarm which wrote a calendar file, and convert
71  * it in memory to the current KAlarm format if possible. The storage
72  * file is not updated. The compatibility of the calendar format is
73  * indicated by the return value.
74  *
75  * @param fileStorage calendar stored in local file
76  * @param versionString receives calendar's KAlarm version as a string
77  * @return CurrentFormat if the calendar is in the current KAlarm format;
78  * IncompatibleFormat calendar is not a KAlarm format or is an
79  unknown KAlarm format;
80  * >0 the older KAlarm version which wrote the calendar
81  */
82 KALARMCAL_EXPORT int updateVersion(const KCalendarCore::FileStorage::Ptr &, QString &versionString);
83 
84 /** Set the KAlarm version custom property for a calendar. */
85 KALARMCAL_EXPORT void setKAlarmVersion(const KCalendarCore::Calendar::Ptr &);
86 
87 /** Set the program name and version for use in calendars. */
88 KALARMCAL_EXPORT void setProductId(const QByteArray &progName, const QByteArray &progVersion);
89 
90 /** Return the product ID string for use in calendars.
91  * setProductId() must have been called previously.
92  */
93 KALARMCAL_EXPORT QByteArray icalProductId();
94 
95 extern const QByteArray APPNAME; //!< The application name ("KALARM") used in calendar properties
96 } // namespace KACalendar
97 
98 //
99 
100 /**
101  * @short Class representing type attributes of a KAlarm event.
102  *
103  * CalEvent provides methods to manipulate a KAEvent UID according to its category
104  * (active, archived or template). It also provides methods to access KAEvent
105  * mime types.
106  *
107  * @author David Jarvie <[email protected]>
108  */
109 namespace CalEvent
110 {
111 /** The category of an event, indicated by the middle part of its UID. */
112 enum Type {
113  EMPTY = 0, //!< the event has no alarms
114  ACTIVE = 0x01, //!< the event is currently active
115  ARCHIVED = 0x02, //!< the event is archived
116  TEMPLATE = 0x04, //!< the event is an alarm template
117  DISPLAYING = 0x08 //!< the event is currently being displayed
118 };
119 Q_DECLARE_FLAGS(Types, Type)
120 
121 KALARMCAL_EXPORT QString uid(const QString &id, Type);
122 KALARMCAL_EXPORT Type status(const KCalendarCore::Event::Ptr &, QString *param = nullptr);
123 KALARMCAL_EXPORT void setStatus(const KCalendarCore::Event::Ptr &, Type, const QString &param = QString());
124 
125 /** Return the alarm Type for a mime type string. */
126 KALARMCAL_EXPORT Type type(const QString &mimeType);
127 /** Return the alarm Types for a list of mime type strings. */
128 KALARMCAL_EXPORT Types types(const QStringList &mimeTypes);
129 /** Return the mime type string corresponding to an alarm Type. */
130 KALARMCAL_EXPORT QString mimeType(Type);
131 /** Return the mime type strings corresponding to alarm Types. */
132 KALARMCAL_EXPORT QStringList mimeTypes(Types);
133 } // namespace CalEvent
134 
135 Q_DECLARE_OPERATORS_FOR_FLAGS(CalEvent::Types)
136 
137 } // namespace KAlarmCal
138 
139 KALARMCAL_EXPORT QDebug operator<<(QDebug, KAlarmCal::CalEvent::Type);
140 
141 
142 // vim: et sw=4:
the event is an alarm template
Definition: kacalendar.h:116
void setKAlarmVersion(const Calendar::Ptr &calendar)
Set the KAlarm version custom property for a calendar.
Definition: kacalendar.cpp:70
not written by KAlarm, or a newer KAlarm version
Definition: kacalendar.h:67
not written by KAlarm, or in a newer KAlarm version
Definition: kacalendar.h:57
in an older KAlarm format
Definition: kacalendar.h:56
QByteArray icalProductId()
Return the product ID string for use in calendars.
Definition: kacalendar.cpp:62
Type
The category of an event, indicated by the middle part of its UID.
Definition: kacalendar.h:112
in current KAlarm format, but not yet saved
Definition: kacalendar.h:55
const QByteArray APPNAME("KALARM")
The application name ("KALARM") used in calendar properties.
Definition: kacalendar.h:95
the event is currently being displayed
Definition: kacalendar.h:117
the event is currently active
Definition: kacalendar.h:114
int updateVersion(const FileStorage::Ptr &fileStorage, QString &versionString)
Check the version of KAlarm which wrote a calendar file, and convert it in memory to the current KAla...
Definition: kacalendar.cpp:81
in current KAlarm format
Definition: kacalendar.h:54
the event has no alarms
Definition: kacalendar.h:113
current KAlarm format
Definition: kacalendar.h:65
the event is archived
Definition: kacalendar.h:115
void setProductId(const QByteArray &progName, const QByteArray &progVersion)
Set the program name and version for use in calendars.
Definition: kacalendar.cpp:57
calendar may contain more than one version
Definition: kacalendar.h:66
Compatibility
Compatibility of resource backend calendar format.
Definition: kacalendar.h:52
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Oct 16 2021 23:12:56 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.