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 * @short Phonenumber information.
25 *
26 * This class provides phone number information. A phone number is classified by
27 * a type. The following types are available, it's possible to use multiple types
28 * Types for a number by combining them through a logical or.
29 */
30class KCONTACTS_EXPORT PhoneNumber
31{
32 friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &, const PhoneNumber &);
33 friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &, PhoneNumber &);
34 friend class VCardTool;
35
36 Q_GADGET
37 Q_PROPERTY(QString id READ id WRITE setId)
38 Q_PROPERTY(QString number READ number WRITE setNumber)
39 Q_PROPERTY(QString normalizedNumber READ normalizedNumber)
40 Q_PROPERTY(Type type READ type WRITE setType)
41 Q_PROPERTY(QString typeLabel READ typeLabel)
42 Q_PROPERTY(bool isEmpty READ isEmpty)
43 Q_PROPERTY(bool isPreferred READ isPreferred)
44 Q_PROPERTY(bool supportsSms READ supportsSms)
45
46public:
47 /**
48 Phone number types.
49 @see Type
50 */
51 enum TypeFlag {
52 Home = 1, /**< Home number */
53 Work = 2, /**< Office number */
54 Msg = 4, /**< Messaging */
55 Pref = 8, /**< Preferred number */
56 Voice = 16, /**< Voice */
57 Fax = 32, /**< Fax machine */
58 Cell = 64, /**< Cell phone */
59 Video = 128, /**< Video phone */
60 Bbs = 256, /**< Mailbox */
61 Modem = 512, /**< Modem */
62 Car = 1024, /**< Car phone */
63 Isdn = 2048, /**< ISDN connection */
64 Pcs = 4096, /**< Personal Communication Service*/
65 Pager = 8192, /**< Pager */
66 // TODO add Text and textphone support vcard4
67 Undefined = 16384, /** Undefined number type */
68 };
69
70 /**
71 * Stores a combination of #TypeFlag values.
72 */
73 Q_DECLARE_FLAGS(Type, TypeFlag)
74 Q_FLAG(Type)
75
76 /**
77 * List of phone number types.
78 */
79 typedef QList<TypeFlag> TypeList;
80
81 /**
82 * List of phone numbers.
83 */
84 typedef QList<PhoneNumber> List;
85
86 /**
87 * Creates an empty phone number object.
88 */
89 PhoneNumber();
90
91 /**
92 * Creates a phone number object.
93 *
94 * @param number Number
95 * @param type Type as defined in enum. Multiple types can be
96 * specified by combining them by a logical or.
97 */
98 PhoneNumber(const QString &number, Type type = Home); // krazy:exclude=explicit
99
100 /**
101 * Copy constructor.
102 *
103 * Fast operation, PhoneNumber's data is implicitly shared.
104 *
105 * @param other The PhoneNumber object to copy from
106 */
107 PhoneNumber(const PhoneNumber &other);
108
109 /**
110 * Destroys the phone number.
111 */
112 ~PhoneNumber();
113
114 /**
115 * Equality operator.
116 *
117 * @return @c true if number, type and identifier are equal,
118 * otherwise @c false
119 */
120 Q_REQUIRED_RESULT bool operator==(const PhoneNumber &other) const;
121
122 /**
123 * Not-Equal operator.
124 */
125 Q_REQUIRED_RESULT bool operator!=(const PhoneNumber &other) const;
126
127 /**
128 * Assignment operator.
129 *
130 * Fast operation, PhoneNumber's data is implicitly shared.
131 *
132 * @param other The PhoneNumber object to asssign to @c this
133 */
134 PhoneNumber &operator=(const PhoneNumber &other);
135
136 /**
137 * Returns true, if the phone number is empty.
138 */
139 Q_REQUIRED_RESULT bool isEmpty() const;
140
141 /**
142 * Sets the unique @p identifier.
143 */
144 void setId(const QString &identifier);
145
146 /**
147 * Returns the unique identifier.
148 */
149 Q_REQUIRED_RESULT QString id() const;
150
151 /**
152 * Sets the phone @p number.
153 */
154 void setNumber(const QString &number);
155
156 /**
157 * Returns the phone number.
158 * This is the number as entered/stored with all formatting preserved. Preferred for display.
159 * @see normalizedNumber()
160 */
161 Q_REQUIRED_RESULT QString number() const;
162
163 /**
164 * Returns the phone number normalized for dialing.
165 * This has all formatting stripped for passing to dialers or tel: URLs.
166 * @see number()
167 * @since 5.12
168 */
169 Q_REQUIRED_RESULT QString normalizedNumber() const;
170
171 /**
172 * Sets the @p type.
173 * Multiple types can be specified by combining them by a logical or.
174 *
175 * @param type The #Type of the phone number
176 */
177 void setType(Type type);
178
179 /**
180 * Returns the type. Can be a multiple types combined by a logical or.
181 *
182 * @see #TypeFlag
183 * @see typeLabel()
184 */
185 Q_REQUIRED_RESULT Type type() const;
186
187 /**
188 * Returns a translated string of the address' type.
189 */
190 Q_REQUIRED_RESULT QString typeLabel() const;
191
192 /**
193 * Returns a list of all available types
194 */
195 Q_REQUIRED_RESULT static TypeList typeList();
196
197 /**
198 * Returns whether this phone number is marked as preferred.
199 * @since 5.12
200 */
201 Q_REQUIRED_RESULT bool isPreferred() const;
202 /**
203 * Returns whether this phone number is expected to support receiving SMS messages.
204 * @since 5.12
205 */
206 Q_REQUIRED_RESULT bool supportsSms() const;
207
208 /**
209 * Returns the translated label for phone number @p type.
210 *
211 * In opposite to typeFlagLabel( TypeFlag type ), it returns all types
212 * of the phone number concatenated by '/'.
213 *
214 * @param type An OR'ed combination of #TypeFlag
215 *
216 * @see type()
217 */
218 static QString typeLabel(Type type);
219
220 /**
221 * Returns the translated label for phone number @p type.
222 *
223 * @param type An OR'ed combination of #TypeFlag
224 *
225 * @see typeLabel()
226 * @since 4.5
227 */
228 Q_REQUIRED_RESULT static QString typeFlagLabel(TypeFlag type);
229
230 /**
231 * Returns a string representation of the phone number.
232 */
233 QString toString() const;
234
235private:
236 KCONTACTS_NO_EXPORT void setParams(const ParameterMap &params);
237 Q_REQUIRED_RESULT KCONTACTS_NO_EXPORT ParameterMap params() const;
238
239 class Private;
240 QSharedDataPointer<Private> d;
241};
242
243Q_DECLARE_OPERATORS_FOR_FLAGS(PhoneNumber::Type)
244
245/**
246 * Serializes the phone @p number object into the @p stream.
247 *
248 * @param stream The stream to write into
249 * @param number The phone number object to serialize
250 */
251KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const PhoneNumber &number);
252
253/**
254 * Initializes the phone @p number object from the @p stream.
255 *
256 * @param stream The stream to read from
257 * @param number The phone number object to deserialize into
258 */
259KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, PhoneNumber &number);
260}
261
262Q_DECLARE_TYPEINFO(KContacts::PhoneNumber, Q_RELOCATABLE_TYPE);
263
264#endif
265

source code of kcontacts/src/phonenumber.h