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 | |
33 | namespace KABC { |
34 | |
35 | //class DistributionListManager; |
36 | class 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 | */ |
45 | class 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 | */ |
205 | typedef QMap<QString, DistributionList*> DistributionListMap; |
206 | |
207 | } |
208 | #endif |
209 | |