KContacts

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

KDE's Doxygen guidelines are available online.