1/*
2 This file is part of libkabc.
3 Copyright (c) 2001 Cornelius Schumacher <schumacher@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KABC_PHONENUMBER_H
22#define KABC_PHONENUMBER_H
23
24#include "kabc_export.h"
25
26#include <QtCore/QSharedDataPointer>
27#include <QtCore/QString>
28
29namespace KABC {
30
31/**
32 * @short Phonenumber information.
33 *
34 * This class provides phone number information. A phone number is classified by
35 * a type. The following types are available, it's possible to use multiple types
36 * Types for a number by combining them through a logical or.
37*/
38class KABC_EXPORT PhoneNumber
39{
40 friend KABC_EXPORT QDataStream &operator<<( QDataStream &, const PhoneNumber & );
41 friend KABC_EXPORT QDataStream &operator>>( QDataStream &, PhoneNumber & );
42
43 public:
44 /**
45 Phone number types.
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 };
63
64 Q_DECLARE_FLAGS( Type, TypeFlag )
65
66 /**
67 * List of phone number types.
68 */
69 typedef QList<TypeFlag> TypeList;
70
71 /**
72 * List of phone numbers.
73 */
74 typedef QList<PhoneNumber> List;
75
76 /**
77 * Creates an empty phone number object.
78 */
79 PhoneNumber();
80
81 /**
82 * Creates a phone number object.
83 *
84 * @param number Number
85 * @param type Type as defined in enum. Multiple types can be
86 * specified by combining them by a logical or.
87 */
88 PhoneNumber( const QString &number, Type type = Home ); //krazy:exclude=explicit
89
90 /**
91 * Copy constructor.
92 *
93 * Fast operation, PhoneNumber's data is implicitly shared.
94 *
95 * @param other The PhoneNumber object to copy from
96 */
97 PhoneNumber( const PhoneNumber &other );
98
99 /**
100 * Destroys the phone number.
101 */
102 ~PhoneNumber();
103
104 /**
105 * Equality operator.
106 *
107 * @return @c true if number, type and identifier are equal,
108 * otherwise @c false
109 */
110 bool operator==( const PhoneNumber & ) const;
111
112 /**
113 * Not-Equal operator.
114 */
115 bool operator!=( const PhoneNumber & ) const;
116
117 /**
118 * Assignment operator.
119 *
120 * Fast operation, PhoneNumber's data is implicitly shared.
121 *
122 * @param other The PhoneNumber object to asssign to @c this
123 */
124 PhoneNumber &operator=( const PhoneNumber &other );
125
126 /**
127 * Returns true, if the phone number is empty.
128 */
129 bool isEmpty() const;
130
131 /**
132 * Sets the unique @p identifier.
133 */
134 void setId( const QString &identifier );
135
136 /**
137 * Returns the unique identifier.
138 */
139 QString id() const;
140
141 /**
142 * Sets the phone @p number.
143 */
144 void setNumber( const QString &number );
145
146 /**
147 * Returns the phone number.
148 */
149 QString number() const;
150
151 /**
152 * Sets the @p type.
153 * Multiple types can be specified by combining them by a logical or.
154 *
155 * @param type The #Type of the phone number
156 */
157 void setType( Type type );
158
159 /**
160 * Returns the type. Can be a multiple types combined by a logical or.
161 *
162 * @see #TypeFlag
163 * @see typeLabel()
164 */
165 Type type() const;
166
167 /**
168 * Returns a translated string of the address' type.
169 */
170 QString typeLabel() const;
171
172 /**
173 * Returns a list of all available types
174 */
175 static TypeList typeList();
176
177 /**
178 * Returns the translated label for phone number @p type.
179 *
180 * In opposite to typeFlagLabel( TypeFlag type ), it returns all types
181 * of the phone number concatenated by '/'.
182 *
183 * @param type An OR'ed combination of #TypeFlag
184 *
185 * @see type()
186 */
187 static QString typeLabel( Type type );
188
189 /**
190 * Returns the translated label for phone number @p type.
191 *
192 * @param type An OR'ed combination of #TypeFlag
193 *
194 * @see typeLabel()
195 * @since 4.5
196 */
197 static QString typeFlagLabel( TypeFlag type );
198
199 /**
200 * Returns a string representation of the phone number.
201 */
202 QString toString() const;
203
204 private:
205 class Private;
206 QSharedDataPointer<Private> d;
207};
208
209Q_DECLARE_OPERATORS_FOR_FLAGS( PhoneNumber::Type )
210
211/**
212 * Serializes the phone @p number object into the @p stream.
213 *
214 * @param stream The stream to write into
215 * @param number The phone number object to serialize
216 */
217KABC_EXPORT QDataStream &operator<<( QDataStream &stream, const PhoneNumber &number );
218
219/**
220 * Initializes the phone @p number object from the @p stream.
221 *
222 * @param stream The stream to read from
223 * @param number The phone number object to deserialize into
224 */
225KABC_EXPORT QDataStream &operator>>( QDataStream &stream, const PhoneNumber &number );
226
227}
228
229#endif
230