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 Person class. |
26 | |
27 | @author Cornelius Schumacher \<schumacher@kde.org\> |
28 | @author Reinhold Kainhofer \<reinhold@kainhofer.com\> |
29 | */ |
30 | |
31 | #ifndef KCALCORE_PERSON_H |
32 | #define KCALCORE_PERSON_H |
33 | |
34 | #include "kcalcore_export.h" |
35 | |
36 | #include <QtCore/QString> |
37 | #include <QtCore/QHash> |
38 | #include <QtCore/QMetaType> |
39 | #include <QtCore/QSharedPointer> |
40 | |
41 | namespace KCalCore { |
42 | |
43 | /** |
44 | @brief |
45 | Represents a person, by name and email address. |
46 | |
47 | This class represents a person, with a name and an email address. |
48 | It supports the "FirstName LastName\ <mail@domain\>" format. |
49 | */ |
50 | class KCALCORE_EXPORT Person |
51 | { |
52 | public: |
53 | /** |
54 | A shared pointer to a Person object. |
55 | */ |
56 | typedef QSharedPointer<Person> Ptr; |
57 | |
58 | /** |
59 | List of persons. |
60 | */ |
61 | typedef QVector<Ptr> List; |
62 | |
63 | /** |
64 | Constructs a blank person. |
65 | */ |
66 | Person(); |
67 | |
68 | /** |
69 | Constructs a person with name and email address taken from @p fullName. |
70 | |
71 | @param fullName is the name and email of the person in the form |
72 | "FirstName LastName \<mail@domain\>". |
73 | @return A Person object pointer. |
74 | */ |
75 | static Person::Ptr fromFullName(const QString &fullName); |
76 | |
77 | /** |
78 | Constructs a person with the name @p name and email address @p email. |
79 | |
80 | @param name is the name of this person. |
81 | @param email is the email address of this person. |
82 | */ |
83 | Person(const QString &name, const QString &email); |
84 | |
85 | /** |
86 | Constructs a person as a copy of another person object. |
87 | @param person is the person to copy. |
88 | */ |
89 | Person(const Person &person); |
90 | |
91 | /** |
92 | Destroys a person. |
93 | */ |
94 | virtual ~Person(); |
95 | |
96 | /** |
97 | Returns true if the person name and email address are empty. |
98 | */ |
99 | bool isEmpty() const; |
100 | |
101 | /** |
102 | Returns the full name of this person. |
103 | @return A QString containing the person's full name in the form |
104 | "FirstName LastName \<mail@domain\>". |
105 | */ |
106 | QString fullName() const; |
107 | |
108 | /** |
109 | Sets the name of the person to @p name. |
110 | |
111 | @param name is the name of this person. |
112 | |
113 | @see name() |
114 | */ |
115 | void setName(const QString &name); |
116 | |
117 | /** |
118 | Returns the person name string. |
119 | |
120 | @see setName() |
121 | */ |
122 | QString name() const; |
123 | |
124 | /** |
125 | Sets the email address for this person to @p email. |
126 | |
127 | @param email is the email address for this person. |
128 | |
129 | @see email() |
130 | */ |
131 | void setEmail(const QString &email); |
132 | |
133 | /** |
134 | Returns the email address for this person. |
135 | @return A QString containing the person's email address. |
136 | @see setEmail() |
137 | */ |
138 | QString email() const; |
139 | |
140 | /** |
141 | Returns true if person's email address is valid. |
142 | Simple email validity check, test that there: |
143 | * is at least one @ |
144 | * is at least one character in the local part |
145 | * is at least one dot in the domain part |
146 | * is at least four characters in the domain (assuming that no-one has an address at the tld, |
147 | that the tld is at least 2 chars) |
148 | |
149 | @param email is the email address to validate |
150 | */ |
151 | static bool isValidEmail(const QString &email); |
152 | |
153 | /** |
154 | Sets the number of references for this person. |
155 | |
156 | This can be initialized in a loading function (see ExtendedStorage), |
157 | where the number of contact appearances etc. are counted. |
158 | |
159 | @param count number of references |
160 | |
161 | @see count() |
162 | */ |
163 | void setCount(int count); |
164 | |
165 | /** |
166 | Returns the number of references or zero if it is not initialized. |
167 | |
168 | @see setCount() |
169 | */ |
170 | int count() const; |
171 | |
172 | /** |
173 | Compares this with @p person for equality. |
174 | |
175 | @param person is the person to compare. |
176 | */ |
177 | bool operator==(const Person &person) const; |
178 | |
179 | /** |
180 | Compares this with @p person for non-equality. |
181 | |
182 | @param person is the person to compare. |
183 | */ |
184 | bool operator!=(const Person &person) const; |
185 | |
186 | /** |
187 | Sets this person equal to @p person. |
188 | |
189 | @param person is the person to copy. |
190 | */ |
191 | Person &operator=(const Person &person); |
192 | |
193 | private: |
194 | //@cond PRIVATE |
195 | class Private; |
196 | Private *const d; |
197 | //@endcond |
198 | |
199 | // TODO_KDE5: FIXME: This operator does slicing,if the object is in fact one of the derived classes (Attendee) |
200 | friend KCALCORE_EXPORT QDataStream &operator<<(QDataStream &s, |
201 | const KCalCore::Person::Ptr &person); |
202 | friend KCALCORE_EXPORT QDataStream &operator>>(QDataStream &s, |
203 | KCalCore::Person::Ptr &person); |
204 | }; |
205 | |
206 | /** |
207 | Serializes the @p person object into the @p stream. |
208 | */ |
209 | KCALCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KCalCore::Person::Ptr &person); |
210 | |
211 | /** |
212 | Initializes the @p person object from the @p stream. |
213 | */ |
214 | KCALCORE_EXPORT QDataStream &operator>>(QDataStream &stream, KCalCore::Person::Ptr &person); |
215 | |
216 | } |
217 | |
218 | /** |
219 | Return a hash value for a Person argument. |
220 | @param key is a Person. |
221 | */ |
222 | KCALCORE_EXPORT uint qHash(const KCalCore::Person &key); |
223 | |
224 | //@cond PRIVATE |
225 | Q_DECLARE_TYPEINFO(KCalCore::Person::Ptr, Q_MOVABLE_TYPE); |
226 | Q_DECLARE_METATYPE(KCalCore::Person::Ptr) |
227 | //@endcond |
228 | |
229 | #endif |
230 | |