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 | |
19 | namespace KContacts |
20 | { |
21 | class 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 | */ |
30 | class 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 | |
46 | public: |
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 | = 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 | |
235 | private: |
236 | KCONTACTS_NO_EXPORT void setParams(const ParameterMap ¶ms); |
237 | Q_REQUIRED_RESULT KCONTACTS_NO_EXPORT ParameterMap params() const; |
238 | |
239 | class Private; |
240 | QSharedDataPointer<Private> d; |
241 | }; |
242 | |
243 | Q_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 | */ |
251 | KCONTACTS_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 | */ |
259 | KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, PhoneNumber &number); |
260 | } |
261 | |
262 | Q_DECLARE_TYPEINFO(KContacts::PhoneNumber, Q_RELOCATABLE_TYPE); |
263 | |
264 | #endif |
265 | |