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> &params);
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 &params);
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