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_DISTRIBUTIONLIST_H
22#define KABC_DISTRIBUTIONLIST_H
23
24#include "kabc_export.h"
25#ifndef KDEPIM_NO_KRESOURCES
26#include "addressbook.h"
27#else
28#include "addressee.h"
29#include <QtCore/QMap>
30#endif
31#include <QtCore/QList>
32
33namespace KABC {
34
35//class DistributionListManager;
36class Resource;
37
38/**
39 @short Distribution list of email addresses
40
41 This class represents a list of email addresses. Each email address is
42 associated with an address book entry. If the address book entry changes, the
43 entry in the distribution list is automatically updated.
44*/
45class KABC_DEPRECATED_EXPORT DistributionList
46{
47 public:
48 /**
49 @short Distribution List Entry
50
51 This class represents an entry of a distribution list. It consists of an
52 addressee and an email address. If the email address is null, the
53 preferred email address of the addressee is used.
54 */
55 class KABC_EXPORT Entry
56 {
57 public:
58 /**
59 A list of Entry instances
60 */
61 typedef QList<Entry> List;
62
63 /**
64 Creates an empty Entry instance
65 */
66 Entry();
67
68 /**
69 Copy constructor.
70
71 @param other The Entry to copy from
72 */
73 Entry( const Entry &other );
74
75 /**
76 Creates an Entry instance.
77
78 @param addressee The addressee of the list entry.
79 @param email The email address. If @c QString() the preferred email
80 of the @p addressee will be used instead
81 */
82 Entry( const Addressee &addressee, const QString &email );
83
84 /**
85 Destroys the Entry instance.
86 */
87 ~Entry();
88
89 /**
90 Assignment operator.
91
92 @param other The Entry to assign to @c this
93 */
94 Entry &operator=( const Entry &other );
95
96 /**
97 Returns the addressee of the list entry.
98 */
99 Addressee addressee() const;
100
101 /**
102 Returns the email address of the list entry.
103
104 @return @c QString() if no specific email address has been set
105 */
106 QString email() const;
107
108 private:
109 class Private;
110 Private *const d;
111 };
112
113 /**
114 Create distribution list object.
115
116 @param resource The resource the list belongs to.
117 @param name Name of this list.
118 */
119 DistributionList( Resource *resource, const QString &name );
120
121 /**
122 Create distribution list object.
123
124 @param resource The resource the list belongs to.
125 @param identifier Identifier of this list.
126 @param name Name of this list.
127 */
128 DistributionList( Resource *resource, const QString &identifier,
129 const QString &name );
130
131 /**
132 Destructor.
133 */
134 ~DistributionList();
135
136 /**
137 Sets the @p identifier of this list which is used as key by resources
138
139 @param identifier A unique identifier of the distribution list
140 */
141 void setIdentifier( const QString &identifier );
142
143 /**
144 Returns the distribution list's identifier
145 */
146 QString identifier() const;
147
148 /**
149 Set name of this list.
150
151 This is a i18n string for display to the user
152 */
153 void setName( const QString & );
154
155 /**
156 Get name of this list.
157 */
158 QString name() const;
159
160 /**
161 Insert an entry into this distribution list. If the entry already exists
162 nothing happens.
163
164 @param email Email address to use for comparison with already inserted
165 entries. If the same addressee is already in the list but
166 the @p email is not the same, insert it again, otherwise
167 update the already existing entry
168 */
169 void insertEntry( const Addressee &, const QString &email=QString() );
170
171 /**
172 Remove an entry from this distribution list. If the entry doesn't exist
173 nothing happens.
174
175 @param email Email address to use as an additional check, since the
176 same addressee entry can be in the list multiple times
177 but with different emails
178 */
179 void removeEntry( const Addressee &, const QString &email=QString() );
180
181 /**
182 Return list of email addresses, which belong to this distributon list.
183 These addresses can be directly used by e.g. a mail client.
184 */
185 QStringList emails() const;
186
187 /**
188 Return list of entries belonging to this distribution list. This function
189 is mainly useful for a distribution list editor.
190 */
191 Entry::List entries() const;
192
193 Resource *resource() const;
194
195 private:
196 class Private;
197 Private *const d;
198
199 Q_DISABLE_COPY( DistributionList )
200};
201
202/**
203 Typedef for map from IDs to respective DistribtionList
204*/
205typedef QMap<QString, DistributionList*> DistributionListMap;
206
207}
208#endif
209