1/*
2 This file is part of the KContacts framework.
3 SPDX-FileCopyrightText: 2001 Cornelius Schumacher <schumacher@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KCONTACTS_PHONENUMBER_H
9#define KCONTACTS_PHONENUMBER_H
10
11#include "kcontacts_export.h"
12
13#include <QList>
14#include <QMap>
15#include <QMetaType>
16#include <QSharedDataPointer>
17#include <QString>
18
19namespace KContacts
20{
21class ParameterMap;
22
23/*!
24 * \qmlvaluetype phoneNumber
25 * \inqmlmodule org.kde.contacts
26 * \nativetype KContacts::PhoneNumber
27 *
28 * \brief Phonenumber information.
29 *
30 * This class provides phone number information. A phone number is classified by
31 * a type. The following types are available, it's possible to use multiple types
32 * Types for a number by combining them through a logical or.
33 */
34
35/*!
36 * \class KContacts::PhoneNumber
37 * \inheaderfile KContacts/PhoneNumber
38 * \inmodule KContacts
39 *
40 * \brief Phonenumber information.
41 *
42 * This class provides phone number information. A phone number is classified by
43 * a type. The following types are available, it's possible to use multiple types
44 * Types for a number by combining them through a logical or.
45 */
46class KCONTACTS_EXPORT PhoneNumber
47{
48 friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &, const PhoneNumber &);
49 friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &, PhoneNumber &);
50 friend class VCardTool;
51
52 Q_GADGET
53
54 /*!
55 * \qmlproperty string phoneNumber::id
56 */
57
58 /*!
59 * \property KContacts::PhoneNumber::id
60 */
61 Q_PROPERTY(QString id READ id WRITE setId)
62
63 /*!
64 * \qmlproperty string phoneNumber::number
65 */
66
67 /*!
68 * \property KContacts::PhoneNumber::number
69 */
70 Q_PROPERTY(QString number READ number WRITE setNumber)
71
72 /*!
73 * \qmlproperty string phoneNumber::normalizedNumber
74 */
75
76 /*!
77 * \property KContacts::PhoneNumber::normalizedNumber
78 */
79 Q_PROPERTY(QString normalizedNumber READ normalizedNumber)
80
81 /*!
82 * \qmlproperty enumeration phoneNumber::type
83 * \qmlenumeratorsfrom KContacts::PhoneNumber::TypeFlag
84 */
85
86 /*!
87 * \property KContacts::PhoneNumber::type
88 */
89 Q_PROPERTY(Type type READ type WRITE setType)
90
91 /*!
92 * \qmlproperty string phoneNumber::typeLabel
93 */
94
95 /*!
96 * \property KContacts::PhoneNumber::typeLabel
97 */
98 Q_PROPERTY(QString typeLabel READ typeLabel)
99
100 /*!
101 * \qmlproperty bool phoneNumber::isEmpty
102 */
103
104 /*!
105 * \property KContacts::PhoneNumber::isEmpty
106 */
107 Q_PROPERTY(bool isEmpty READ isEmpty)
108
109 /*!
110 * \qmlproperty bool phoneNumber::isPreferred
111 */
112
113 /*!
114 * \property KContacts::PhoneNumber::isPreferred
115 */
116 Q_PROPERTY(bool isPreferred READ isPreferred)
117
118 /*!
119 * \qmlproperty bool phoneNumber::supportsSms
120 */
121
122 /*!
123 * \property KContacts::PhoneNumber::supportsSms
124 */
125 Q_PROPERTY(bool supportsSms READ supportsSms)
126
127public:
128 /*!
129 Phone number types.
130
131 \value Home Home number
132 \value Work Office number
133 \value Msg Messaging
134 \value Pref Preferred number
135 \value Voice Voice
136 \value Fax Fax machine
137 \value Cell Cell phone
138 \value Video Video phone
139 \value Bbs Mailbox
140 \value Modem Modem
141 \value Car Car phone
142 \value Isdn ISDN connection
143 \value Pcs Personal Communication Service
144 \value Pager Pager
145 \value Undefined Undefined number type
146 */
147 enum TypeFlag {
148 Home = 1,
149 Work = 2,
150 Msg = 4,
151 Pref = 8,
152 Voice = 16,
153 Fax = 32,
154 Cell = 64,
155 Video = 128,
156 Bbs = 256,
157 Modem = 512,
158 Car = 1024,
159 Isdn = 2048,
160 Pcs = 4096,
161 Pager = 8192,
162 // TODO add Text and textphone support vcard4
163 Undefined = 16384,
164 };
165
166 Q_DECLARE_FLAGS(Type, TypeFlag)
167 Q_FLAG(Type)
168
169 /*!
170 * List of phone number types.
171 */
172 typedef QList<TypeFlag> TypeList;
173
174 /*!
175 * List of phone numbers.
176 */
177 typedef QList<PhoneNumber> List;
178
179 /*!
180 * Creates an empty phone number object.
181 */
182 PhoneNumber();
183
184 /*!
185 * Creates a phone number object.
186 *
187 * \a number Number
188 *
189 * \a type Type as defined in enum. Multiple types can be
190 * specified by combining them by a logical or.
191 */
192 PhoneNumber(const QString &number, Type type = Home); // krazy:exclude=explicit
193
194 /*!
195 * Copy constructor.
196 *
197 * Fast operation, PhoneNumber's data is implicitly shared.
198 *
199 * \a other The PhoneNumber object to copy from
200 */
201 PhoneNumber(const PhoneNumber &other);
202
203 ~PhoneNumber();
204
205 /*!
206 * Equality operator.
207 *
208 * Returns \c true if number, type and identifier are equal,
209 * otherwise \c false
210 */
211 Q_REQUIRED_RESULT bool operator==(const PhoneNumber &other) const;
212
213 /*!
214 * Not-Equal operator.
215 */
216 Q_REQUIRED_RESULT bool operator!=(const PhoneNumber &other) const;
217
218 /*!
219 * Assignment operator.
220 *
221 * Fast operation, PhoneNumber's data is implicitly shared.
222 *
223 * \a other The PhoneNumber object to asssign to \c this
224 */
225 PhoneNumber &operator=(const PhoneNumber &other);
226
227 /*!
228 * Returns true, if the phone number is empty.
229 */
230 Q_REQUIRED_RESULT bool isEmpty() const;
231
232 /*!
233 * Sets the unique \a identifier.
234 */
235 void setId(const QString &identifier);
236
237 /*!
238 * Returns the unique identifier.
239 */
240 Q_REQUIRED_RESULT QString id() const;
241
242 /*!
243 * Sets the phone \a number.
244 */
245 void setNumber(const QString &number);
246
247 /*!
248 * Returns the phone number.
249 * This is the number as entered/stored with all formatting preserved. Preferred for display.
250 * \sa normalizedNumber()
251 */
252 Q_REQUIRED_RESULT QString number() const;
253
254 /*!
255 * Returns the phone number normalized for dialing.
256 * This has all formatting stripped for passing to dialers or tel: URLs.
257 * \sa number()
258 * \since 5.12
259 */
260 Q_REQUIRED_RESULT QString normalizedNumber() const;
261
262 /*!
263 * Sets the \a type.
264 * Multiple types can be specified by combining them by a logical or.
265 *
266 * \a type The #Type of the phone number
267 */
268 void setType(Type type);
269
270 /*!
271 * Returns the type. Can be a multiple types combined by a logical or.
272 *
273 * \sa TypeFlag
274 * \sa typeLabel()
275 */
276 Q_REQUIRED_RESULT Type type() const;
277
278 /*!
279 * Returns a translated string of the address' type.
280 */
281 Q_REQUIRED_RESULT QString typeLabel() const;
282
283 /*!
284 * Returns a list of all available types
285 */
286 Q_REQUIRED_RESULT static TypeList typeList();
287
288 /*!
289 * Returns whether this phone number is marked as preferred.
290 * \since 5.12
291 */
292 Q_REQUIRED_RESULT bool isPreferred() const;
293 /*!
294 * Returns whether this phone number is expected to support receiving SMS messages.
295 * \since 5.12
296 */
297 Q_REQUIRED_RESULT bool supportsSms() const;
298
299 /*!
300 * Returns the translated label for phone number \a type.
301 *
302 * In opposite to typeFlagLabel( TypeFlag type ), it returns all types
303 * of the phone number concatenated by '/'.
304 *
305 * \a type An OR'ed combination of #TypeFlag
306 *
307 * \sa type()
308 */
309 static QString typeLabel(Type type);
310
311 /*!
312 * Returns the translated label for phone number \a type.
313 *
314 * \a type An OR'ed combination of #TypeFlag
315 *
316 * \sa typeLabel()
317 * \since 4.5
318 */
319 Q_REQUIRED_RESULT static QString typeFlagLabel(TypeFlag type);
320
321 /*!
322 * Returns a string representation of the phone number.
323 */
324 QString toString() const;
325
326private:
327 KCONTACTS_NO_EXPORT void setParams(const ParameterMap &params);
328 Q_REQUIRED_RESULT KCONTACTS_NO_EXPORT ParameterMap params() const;
329
330 class Private;
331 QSharedDataPointer<Private> d;
332};
333
334Q_DECLARE_OPERATORS_FOR_FLAGS(PhoneNumber::Type)
335
336/*!
337 * \relates KContacts::PhoneNumber
338 *
339 * Serializes the phone \a number object into the \a stream.
340 *
341 * \a stream The stream to write into
342 *
343 * \a number The phone number object to serialize
344 */
345KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const PhoneNumber &number);
346
347/*!
348 * \relates KContacts::PhoneNumber
349 *
350 * Initializes the phone \a number object from the \a stream.
351 *
352 * \a stream The stream to read from
353 *
354 * \a number The phone number object to deserialize into
355 */
356KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, PhoneNumber &number);
357}
358
359Q_DECLARE_TYPEINFO(KContacts::PhoneNumber, Q_RELOCATABLE_TYPE);
360
361#endif
362

source code of kcontacts/src/phonenumber.h