1 | /* |
2 | This file is part of kdepim. |
3 | |
4 | Copyright (c) 2004 Tobias Koenig <tokoe@kde.org> |
5 | Copyright (c) 2004 Cornelius Schumacher <schumacher@kde.org> |
6 | |
7 | This library is free software; you can redistribute it and/or |
8 | modify it under the terms of the GNU Library General Public |
9 | License as published by the Free Software Foundation; either |
10 | version 2 of the License, or (at your option) any later version. |
11 | |
12 | This library is distributed in the hope that it will be useful, |
13 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 | Library General Public License for more details. |
16 | |
17 | You should have received a copy of the GNU Library General Public License |
18 | along with this library; see the file COPYING.LIB. If not, write to |
19 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
20 | Boston, MA 02110-1301, USA. |
21 | */ |
22 | /** |
23 | @file |
24 | This file is part of the KDE resource framework and defines the |
25 | IdMapper class. |
26 | |
27 | @author Tobias Koenig |
28 | @author Cornelius Schumacher |
29 | */ |
30 | |
31 | #ifndef KRESOURCES_IDMAPPER_H |
32 | #define KRESOURCES_IDMAPPER_H |
33 | |
34 | #include <QtCore/QMap> |
35 | #include <QtCore/QString> |
36 | |
37 | #include "kresources_export.h" |
38 | |
39 | namespace KRES { |
40 | |
41 | class IdMapperPrivate; |
42 | |
43 | /** |
44 | @brief |
45 | Keeps a map of paths and identifiers. |
46 | |
47 | An Id Mapper maps Ids. What to or what for is not entirely |
48 | clear, but maps have categories. This is probably an |
49 | adjoint functor, since adjoint functors are everywhere. |
50 | */ |
51 | class KRESOURCES_DEPRECATED_EXPORT IdMapper |
52 | { |
53 | public: |
54 | /** |
55 | Create Id mapper. You have to set path and identifier before you can call |
56 | load() or save(). |
57 | */ |
58 | IdMapper(); |
59 | |
60 | /** |
61 | Create Id mapper. The path specifies the category of mapping, the |
62 | identifier the concrete object. |
63 | |
64 | If you don't pass an identifier you have to set it before calling load() |
65 | or save(). |
66 | |
67 | The current implementation stores the data at |
68 | $(KDEHOME)/share/apps/\<path\>/\<identifier\>. |
69 | |
70 | @param path Category of mapping (path into the mapping namespace) |
71 | @param identifier The concrete mapping object (filename in namespace) |
72 | */ |
73 | explicit IdMapper( const QString &path, |
74 | const QString &identifier = QString() ); |
75 | |
76 | /** Destructor. */ |
77 | ~IdMapper(); |
78 | |
79 | /** |
80 | Set id map path. |
81 | @param path Path to use into mapping namespace. |
82 | @see IdMapper() |
83 | */ |
84 | void setPath( const QString &path ); |
85 | |
86 | /** |
87 | Return id map path. |
88 | */ |
89 | QString path() const; |
90 | |
91 | /** |
92 | Set id map identifier. |
93 | @param identifier the identifier (filename) within the mapping namespace |
94 | */ |
95 | void setIdentifier( const QString &identifier ); |
96 | |
97 | /** |
98 | Return id map identifier. |
99 | */ |
100 | QString identifier() const; |
101 | |
102 | /** |
103 | Loads the map. |
104 | */ |
105 | bool load(); |
106 | |
107 | /** |
108 | Saves the map. |
109 | */ |
110 | bool save(); |
111 | |
112 | /** |
113 | Clears the map. |
114 | */ |
115 | void clear(); |
116 | |
117 | /** |
118 | Stores the remote id for the given local id. |
119 | @param localId Local Id to set remote for. |
120 | @param remoteId Remote Id to associate with this local Id. |
121 | @see remoteId() |
122 | @see localId() |
123 | @todo What happens when you set the same remote Id for more than |
124 | one localId? |
125 | */ |
126 | void setRemoteId( const QString &localId, const QString &remoteId ); |
127 | |
128 | /** |
129 | Removes the remote id. |
130 | @param remoteId remote Id to remove. |
131 | @todo So what does that do? Remove local Ids with only that |
132 | one remote Id? Remove the remote Id from all local Ids |
133 | that have it? |
134 | @see setRemoteId() |
135 | */ |
136 | void removeRemoteId( const QString &remoteId ); |
137 | |
138 | /** |
139 | Returns the remote id of the given local id. |
140 | @param localId Local Id to get the remote Id from. |
141 | @see setRemoteId() |
142 | @see removeRemoteId() |
143 | */ |
144 | QString remoteId( const QString &localId ) const; |
145 | |
146 | /** |
147 | Returns the local id for the given remote id. |
148 | @param remoteId Remote Id to get the local Id for. |
149 | */ |
150 | QString localId( const QString &remoteId ) const; |
151 | |
152 | /** |
153 | Stores a fingerprint for an id which can be used to detect if |
154 | the locally held version differs from what is on the server. |
155 | This can be a sequence number of an md5 hash depending on what |
156 | the server provides. |
157 | |
158 | @param localId Local Id to set the fingerprint on. |
159 | @param fingerprint Fingerprint (any string will do, though |
160 | an md5 hash is probably a good idea) of the Id. |
161 | */ |
162 | void setFingerprint( const QString &localId, const QString &fingerprint ); |
163 | |
164 | /** |
165 | Returns the fingerprint for the map. |
166 | |
167 | @param localId Local Id to get the fingerprint for. |
168 | @todo Figure out if this returns the last fingerprint set |
169 | by setFingerprint() only or if anything else can change it. |
170 | */ |
171 | QString fingerprint( const QString &localId ) const; |
172 | |
173 | /** |
174 | Returns the entire map of local-to-remote Ids. |
175 | */ |
176 | QMap<QString, QString> remoteIdMap() const; |
177 | |
178 | /** |
179 | Returns a string representation of the id pairs, that's useful |
180 | for debugging. |
181 | */ |
182 | QString asString() const; |
183 | |
184 | protected: |
185 | /** |
186 | Filename of the map when stored on disk. Used in save() and load(), |
187 | @see IdMapper( const QString &path, const QString &identifier ) |
188 | */ |
189 | QString filename(); |
190 | |
191 | private: |
192 | IdMapperPrivate *const d; |
193 | }; |
194 | |
195 | } |
196 | |
197 | #endif |
198 | |