File indexing completed on 2024-10-27 09:54:50
0001 /* 0002 This file is part of the KContacts framework. 0003 SPDX-FileCopyrightText: 2001 Cornelius Schumacher <schumacher@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef KCONTACTS_PHONENUMBER_H 0009 #define KCONTACTS_PHONENUMBER_H 0010 0011 #include "kcontacts_export.h" 0012 0013 #include <QMap> 0014 #include <QMetaType> 0015 #include <QSharedDataPointer> 0016 #include <QString> 0017 #include <QVector> 0018 0019 namespace KContacts 0020 { 0021 class ParameterMap; 0022 0023 /** 0024 * @short Phonenumber information. 0025 * 0026 * This class provides phone number information. A phone number is classified by 0027 * a type. The following types are available, it's possible to use multiple types 0028 * Types for a number by combining them through a logical or. 0029 */ 0030 class KCONTACTS_EXPORT PhoneNumber 0031 { 0032 friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &, const PhoneNumber &); 0033 friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &, PhoneNumber &); 0034 friend class VCardTool; 0035 0036 Q_GADGET 0037 Q_PROPERTY(QString id READ id WRITE setId) 0038 Q_PROPERTY(QString number READ number WRITE setNumber) 0039 Q_PROPERTY(QString normalizedNumber READ normalizedNumber) 0040 Q_PROPERTY(Type type READ type WRITE setType) 0041 Q_PROPERTY(QString typeLabel READ typeLabel) 0042 Q_PROPERTY(bool isEmpty READ isEmpty) 0043 Q_PROPERTY(bool isPreferred READ isPreferred) 0044 Q_PROPERTY(bool supportsSms READ supportsSms) 0045 0046 public: 0047 /** 0048 Phone number types. 0049 @see Type 0050 */ 0051 enum TypeFlag { 0052 Home = 1, /**< Home number */ 0053 Work = 2, /**< Office number */ 0054 Msg = 4, /**< Messaging */ 0055 Pref = 8, /**< Preferred number */ 0056 Voice = 16, /**< Voice */ 0057 Fax = 32, /**< Fax machine */ 0058 Cell = 64, /**< Cell phone */ 0059 Video = 128, /**< Video phone */ 0060 Bbs = 256, /**< Mailbox */ 0061 Modem = 512, /**< Modem */ 0062 Car = 1024, /**< Car phone */ 0063 Isdn = 2048, /**< ISDN connection */ 0064 Pcs = 4096, /**< Personal Communication Service*/ 0065 Pager = 8192, /**< Pager */ 0066 // TODO add Text and textphone support vcard4 0067 Undefined = 16384, /** Undefined number type */ 0068 }; 0069 0070 /** 0071 * Stores a combination of #TypeFlag values. 0072 */ 0073 Q_DECLARE_FLAGS(Type, TypeFlag) 0074 Q_FLAG(Type) 0075 0076 /** 0077 * List of phone number types. 0078 */ 0079 typedef QVector<TypeFlag> TypeList; 0080 0081 /** 0082 * List of phone numbers. 0083 */ 0084 typedef QVector<PhoneNumber> List; 0085 0086 /** 0087 * Creates an empty phone number object. 0088 */ 0089 PhoneNumber(); 0090 0091 /** 0092 * Creates a phone number object. 0093 * 0094 * @param number Number 0095 * @param type Type as defined in enum. Multiple types can be 0096 * specified by combining them by a logical or. 0097 */ 0098 PhoneNumber(const QString &number, Type type = Home); // krazy:exclude=explicit 0099 0100 /** 0101 * Copy constructor. 0102 * 0103 * Fast operation, PhoneNumber's data is implicitly shared. 0104 * 0105 * @param other The PhoneNumber object to copy from 0106 */ 0107 PhoneNumber(const PhoneNumber &other); 0108 0109 /** 0110 * Destroys the phone number. 0111 */ 0112 ~PhoneNumber(); 0113 0114 /** 0115 * Equality operator. 0116 * 0117 * @return @c true if number, type and identifier are equal, 0118 * otherwise @c false 0119 */ 0120 Q_REQUIRED_RESULT bool operator==(const PhoneNumber &other) const; 0121 0122 /** 0123 * Not-Equal operator. 0124 */ 0125 Q_REQUIRED_RESULT bool operator!=(const PhoneNumber &other) const; 0126 0127 /** 0128 * Assignment operator. 0129 * 0130 * Fast operation, PhoneNumber's data is implicitly shared. 0131 * 0132 * @param other The PhoneNumber object to asssign to @c this 0133 */ 0134 PhoneNumber &operator=(const PhoneNumber &other); 0135 0136 /** 0137 * Returns true, if the phone number is empty. 0138 */ 0139 Q_REQUIRED_RESULT bool isEmpty() const; 0140 0141 /** 0142 * Sets the unique @p identifier. 0143 */ 0144 void setId(const QString &identifier); 0145 0146 /** 0147 * Returns the unique identifier. 0148 */ 0149 Q_REQUIRED_RESULT QString id() const; 0150 0151 /** 0152 * Sets the phone @p number. 0153 */ 0154 void setNumber(const QString &number); 0155 0156 /** 0157 * Returns the phone number. 0158 * This is the number as entered/stored with all formatting preserved. Preferred for display. 0159 * @see normalizedNumber() 0160 */ 0161 Q_REQUIRED_RESULT QString number() const; 0162 0163 /** 0164 * Returns the phone number normalized for dialing. 0165 * This has all formatting stripped for passing to dialers or tel: URLs. 0166 * @see number() 0167 * @since 5.12 0168 */ 0169 Q_REQUIRED_RESULT QString normalizedNumber() const; 0170 0171 /** 0172 * Sets the @p type. 0173 * Multiple types can be specified by combining them by a logical or. 0174 * 0175 * @param type The #Type of the phone number 0176 */ 0177 void setType(Type type); 0178 0179 /** 0180 * Returns the type. Can be a multiple types combined by a logical or. 0181 * 0182 * @see #TypeFlag 0183 * @see typeLabel() 0184 */ 0185 Q_REQUIRED_RESULT Type type() const; 0186 0187 /** 0188 * Returns a translated string of the address' type. 0189 */ 0190 Q_REQUIRED_RESULT QString typeLabel() const; 0191 0192 /** 0193 * Returns a list of all available types 0194 */ 0195 Q_REQUIRED_RESULT static TypeList typeList(); 0196 0197 /** 0198 * Returns whether this phone number is marked as preferred. 0199 * @since 5.12 0200 */ 0201 Q_REQUIRED_RESULT bool isPreferred() const; 0202 /** 0203 * Returns whether this phone number is expected to support receiving SMS messages. 0204 * @since 5.12 0205 */ 0206 Q_REQUIRED_RESULT bool supportsSms() const; 0207 0208 /** 0209 * Returns the translated label for phone number @p type. 0210 * 0211 * In opposite to typeFlagLabel( TypeFlag type ), it returns all types 0212 * of the phone number concatenated by '/'. 0213 * 0214 * @param type An OR'ed combination of #TypeFlag 0215 * 0216 * @see type() 0217 */ 0218 static QString typeLabel(Type type); 0219 0220 /** 0221 * Returns the translated label for phone number @p type. 0222 * 0223 * @param type An OR'ed combination of #TypeFlag 0224 * 0225 * @see typeLabel() 0226 * @since 4.5 0227 */ 0228 Q_REQUIRED_RESULT static QString typeFlagLabel(TypeFlag type); 0229 0230 /** 0231 * Returns a string representation of the phone number. 0232 */ 0233 QString toString() const; 0234 0235 #if KCONTACTS_ENABLE_DEPRECATED_SINCE(5, 88) 0236 /** 0237 * @deprecated Since 5.88 for lack of usage 0238 */ 0239 KCONTACTS_DEPRECATED_VERSION(5, 88, "For lack of usage.") 0240 void setParameters(const QMap<QString, QStringList> ¶ms); 0241 #endif 0242 0243 #if KCONTACTS_ENABLE_DEPRECATED_SINCE(5, 88) 0244 /** 0245 * @deprecated Since 5.88 for lack of usage 0246 */ 0247 Q_REQUIRED_RESULT 0248 KCONTACTS_DEPRECATED_VERSION(5, 88, "For lack of usage.") 0249 QMap<QString, QStringList> parameters() const; 0250 #endif 0251 0252 private: 0253 KCONTACTS_NO_EXPORT void setParams(const ParameterMap ¶ms); 0254 Q_REQUIRED_RESULT KCONTACTS_NO_EXPORT ParameterMap params() const; 0255 0256 class Private; 0257 QSharedDataPointer<Private> d; 0258 }; 0259 0260 Q_DECLARE_OPERATORS_FOR_FLAGS(PhoneNumber::Type) 0261 0262 /** 0263 * Serializes the phone @p number object into the @p stream. 0264 * 0265 * @param stream The stream to write into 0266 * @param number The phone number object to serialize 0267 */ 0268 KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const PhoneNumber &number); 0269 0270 /** 0271 * Initializes the phone @p number object from the @p stream. 0272 * 0273 * @param stream The stream to read from 0274 * @param number The phone number object to deserialize into 0275 */ 0276 KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, PhoneNumber &number); 0277 } 0278 Q_DECLARE_METATYPE(KContacts::PhoneNumber) 0279 Q_DECLARE_TYPEINFO(KContacts::PhoneNumber, Q_MOVABLE_TYPE); 0280 #endif