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
41namespace 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*/
50class KCALCORE_EXPORT Person
51{
52public:
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
193private:
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*/
209KCALCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KCalCore::Person::Ptr &person);
210
211/**
212 Initializes the @p person object from the @p stream.
213*/
214KCALCORE_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*/
222KCALCORE_EXPORT uint qHash(const KCalCore::Person &key);
223
224//@cond PRIVATE
225Q_DECLARE_TYPEINFO(KCalCore::Person::Ptr, Q_MOVABLE_TYPE);
226Q_DECLARE_METATYPE(KCalCore::Person::Ptr)
227//@endcond
228
229#endif
230