1 /***************************************************************************
2 * Copyright (C) 2005-2006 by Tarek Saidi *
3 * tarek.saidi@arcor.de *
5 * This program is free software; you can redistribute it and/or modify *
6 * it under the terms of the GNU General Public License as published by *
7 * the Free Software Foundation; version 2 of the License. *
10 * This program 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 *
13 * GNU General Public License for more details. *
15 * You should have received a copy of the GNU General Public License *
16 * along with this program; if not, write to the *
17 * Free Software Foundation, Inc., *
18 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
19 ***************************************************************************/
24 extern const QDateTime Date_Never;
31 //! Universally Unique Identifier Class.
33 Provides generation, serialization, deserialization and comparison of UUIDs.
38 KpxUuid(const void* src);
40 QString toString() const;
41 const unsigned char* data()const
42 {return (const unsigned char*) Data.data();}
43 void toRaw(void* dst)const;
44 void fromRaw(const void* src);
45 bool operator==(const KpxUuid&) const;
46 bool operator!=(const KpxUuid&) const;
51 //! Advanced DateTime Class.
53 This class advances the standard Qt class 'QDateTime' with KeePassX specific methods for string conversion.
55 class KpxDateTime:public QDateTime{
58 KpxDateTime ( const QDate & date ):QDateTime(date){};
59 KpxDateTime ( const QDate & date, const QTime & time, Qt::TimeSpec spec = Qt::LocalTime):QDateTime(date,time,spec){};
60 KpxDateTime ( const QDateTime & other ):QDateTime(other){};
61 //! Returns a string representation of the DateTime object in the given format or "Never" if the DateTime value is 28.12.2999 23:59:59.
62 virtual QString toString(Qt::DateFormat format = Qt::TextDate ) const;
63 //! Returns a string representation of the date part of the DateTime object in the given format or "Never" if the DateTime value is 28.12.2999 23:59:59.
64 QString dateToString(Qt::DateFormat format = Qt::TextDate)const;
65 static KpxDateTime fromString(const QString& string,Qt::DateFormat format = Qt::TextDate);
66 bool operator<(const QDateTime& other);
69 //! Entry Data Structure
70 /*! This class holds the data of a normal database entry. It is used by some interface functions to process predefined entries and can be used for internal data handling.*/
85 KpxDateTime LastAccess;
88 bool operator==(const CEntry& other) const;
91 //! Group Data Structure
92 /*! This class holds the data of a normal database group. It is used by some interface functions to process predefined groups and can be used for internal data handling.*/
99 bool operator==(const CGroup& other) const;
106 //! Handle class interface for accessing entries
108 The IEntryHandle interface provides access to Entry data structures without using direct references. Every entry handle class must implement this interface necessarily.
112 virtual void setImage(const quint32& ImageID)=0;
113 virtual void setTitle(const QString& Title)=0;
114 virtual void setUrl(const QString& URL)=0;
115 virtual void setUsername(const QString& Username)=0;
116 virtual void setPassword(const SecString& Password)=0;
117 virtual void setComment(const QString& Comment)=0;
118 virtual void setBinaryDesc(const QString& BinaryDesc)=0;
119 virtual void setCreation(const KpxDateTime& Creation)=0;
120 virtual void setLastMod(const KpxDateTime& LastMod)=0;
121 virtual void setLastAccess(const KpxDateTime& LastAccess)=0;
122 virtual void setExpire(const KpxDateTime& Expire)=0;
123 virtual void setBinary(const QByteArray& BinaryData)=0;
125 virtual KpxUuid uuid()const=0;
126 virtual IGroupHandle* group()const=0;
127 virtual quint32 image()const=0;
128 virtual QString title()const=0;
129 virtual QString url()const=0;
130 virtual QString username()const=0;
131 virtual SecString password()const=0;
132 virtual QString comment()const=0;
133 virtual QString binaryDesc()const=0;
134 virtual KpxDateTime creation()const=0;
135 virtual KpxDateTime lastMod()const=0;
136 virtual KpxDateTime lastAccess()const=0;
137 virtual KpxDateTime expire()const=0;
138 virtual QByteArray binary()const=0;
139 virtual quint32 binarySize()const=0;
140 virtual QString friendlySize()const=0;
142 //! \return the index of the entry amongst the entries of its group. The index of the first entry is 0.
143 virtual int visualIndex()const=0;
145 /*! Sets the visual index of an entry. The indices of all other entries in the same group get automaticly readjusted by this function.
146 \param index The new visual index.
148 virtual void setVisualIndex(int index)=0;
150 /*! Sets the visual index of an entry. The indices of all other entries in the same group need to be adjusted manually!
151 This function is optimal to avoid readjustion overhead when sorting items.
152 \param index The new visual index.
154 virtual void setVisualIndexDirectly(int index)=0;
156 /*! Tests the validity of the handle.
157 \return TRUE if the handle is valid and FALSE if the handle is invalid e.g. because the associated entry was deleted.*/
158 virtual bool isValid()const=0;
160 virtual CEntry data()const=0;
163 //! Custom Icon Interface
165 This class provides an interface for the management of custom icons. The implementation is optional and not necessarily needed.
167 class ICustomIcons:public QObject{
170 /*! Adds a new custom icon to the database.
171 \param icon The pixmap which contains the new icon. This function makes a copy of the given pixmap.
173 virtual void addIcon(const QPixmap& icon)=0;
176 \param index The index of the icon which should be removed. Built-in icons cannot be removed so make sure that index is not the index of an Built-in icon before calling this function.
178 virtual void removeIcon(int index)=0;
180 /*! Replaces one icon with another one.
181 \param index The index of the icon which should be replaced. Built-in icons cannot be replaced so make sure that index is not the index of an Built-in icon before calling this function.
182 \param icon The pixmap which contains the new icon.
184 virtual void replaceIcon(int index,const QPixmap& icon)=0;
186 /*! This signal is emitted when an icon was modified.
187 That means it is emitted after every call off addIcon(), removeIcon() and replaceIcon().
189 void iconsModified();
194 //! Handle class interface for accessing groups
196 The IGroupHandle interface provides access to CGroup data structures without using direct references. Every entry handle class must implement this interface necessarily.
200 virtual void setTitle(const QString& Title)=0;
201 virtual void setImage(const quint32& ImageID)=0;
203 virtual QString title()=0;
204 virtual quint32 image()=0;
206 //! \return a pointer to the handle of the parent group or NULL if the group has no parent.
207 virtual IGroupHandle* parent()=0;
209 //! \return a List of pointers to the handles of all children of the group and an empty list if the group has no children. The list is sorted.
210 virtual QList<IGroupHandle*> children()=0;
212 //! \return the index of the group amongst the children of its parent. The index of the first child is 0.
213 virtual int index()=0;
215 /*! Sets the index of a group amongst the children of its parent.
216 This function can be used to sort the groups of the database in a specific order.
217 \param index The new index of the group. The indices of the other groups which are affected by this operation will be automatically adjusted.*/
218 //virtual void setIndex(int index)=0;
220 /*! Tests the validity of the handle.
221 \return TRUE if the handle is valid and FALSE if the handle is invalid e.g. because the associated group was deleted.*/
222 virtual bool isValid()=0;
224 /*! \return the level of the group in the group tree. This level is tantamount to the number of parents that the group has. */
225 virtual int level()=0;
227 virtual bool expanded()=0;
228 virtual void setExpanded(bool)=0;
232 //! Common Database Interface.
234 This is the common base interface for databases. Every database class must implement this interface necessarily.
238 virtual ~IDatabase(){};
240 virtual bool setKey(const QString& password,const QString& keyfile)=0;
241 virtual bool isKeyError()=0;
242 virtual void generateMasterKey()=0;
244 //! Loads a database.
245 /*! It is not allowed to call this function if a database is already loaded.
246 \param identifier Normally this is the filename of the database but it can also be an IP address or something else if the database is not file based.
247 \return TRUE if loading was successfull, otherwise FALSE.
249 virtual bool load(QString identifier, bool readOnly)=0;
251 //! Saves the current database.
252 /*! It is not allowed to call this function if no database is loaded.
253 \return TRUE if saving was successfull, otherwise FALSE.
255 virtual bool save()=0;
257 //! Closes the current database.
258 /*! After a call of this function the database object can be used to load another database.
259 It is not allowed to call this function if no database is loaded.
260 Please note: The database will be closed without saving it in before.
261 * \return TRUE if closing was successfull, otherwise FALSE.
263 virtual bool close()=0;
265 //! Creates a new database.
266 /*! It is not allowed to call this function if a database is already loaded.
267 \return TRUE if saving was successfull, otherwise FALSE.
269 virtual void create()=0;
272 virtual bool changeFile(const QString& filename)=0;
274 virtual QFile* file()=0;
276 //! \return a list with the pointers to the handles of all entries of the database. The list contains only valid handles. The list is not sorted.
277 virtual QList<IEntryHandle*> entries()=0;
279 //! \param Group The group which contains the wanted entries.
280 //! \return a list of pointers to the handles of all entries which belong to the given group. The list contains only valid handles and is sorted in an ascending order regarding to the entry indices.
281 virtual QList<IEntryHandle*> entries(IGroupHandle* Group)=0;
283 //! \param Group The group which contains the wanted entries.
284 //! \return a list of pointers to the handles of all entries which belong to the given group. The list contains only valid handles and is sorted in an ascending order (title, username).
285 virtual QList<IEntryHandle*> entriesSortedStd(IGroupHandle* Group)=0;
287 //! \return a list with the pointers to the handles of all expired entries of the database. The list contains only valid handles. The list is not sorted.
288 virtual QList<IEntryHandle*> expiredEntries()=0;
290 //! \return a list with the pointers to the handles of all entries of the database. The list contains only valid handles and is not sorted.
291 virtual QList<IGroupHandle*> groups()=0;
294 This function might be slower than groups() - denpending on the implementation.
295 \return a list with the pointers to the handles of all entries of the database. The list ist sorted and contains only valid handles.*/
296 virtual QList<IGroupHandle*> sortedGroups()=0;
298 /*! \return handle of the backup group or NULL if it doesn't exist
299 \param create Create the backup group if it doesn't exist
301 virtual IGroupHandle* backupGroup(bool create=false)=0;
303 /*! \return the last error message or an empty QString() object if no error occured.*/
304 virtual QString getError()=0;
306 /*! Creates a clone of a given entry.
307 All attributes besides the UUID are copied, even the creation date.
308 \param entry The handle of the entry which should be cloned.
309 \return a pointer to the handle of the cloned entry.
311 virtual IEntryHandle* cloneEntry(const IEntryHandle* entry)=0;
313 /*! Deletes a given entry.
314 \param entry The handle of the entry which should be deleted.
316 virtual void deleteEntry(IEntryHandle* entry)=0;
319 /*! Deletes the last added entry.
320 This function should only be called immediately after an addEntry() call, otherwise the behavior is undefined. Immediately means that there are no other add/move/delete operations between the two function calls.*/
321 virtual void deleteLastEntry()=0;
324 /*! Deletes multiple given entries.
325 Calling this function can be faster then calling deleteEntry(..) several times - depending on the implementation.
326 Important: All entries must belong to the same group!
327 \param entries A pointer list of handles of the entries which sould be deleted. The list can be empty therefore no prior testing is necessary.*/
328 virtual void deleteEntries(QList<IEntryHandle*> entries)=0;
331 /*! Creates a new blank entry.
332 \param Group The group to which the entry should be added.
333 \return the handle of the new entry.
335 virtual IEntryHandle* newEntry(IGroupHandle* Group)=0;
337 /*! Adds a Entry object to the database.
338 \param Group The group to which the entry should be added.
339 \param NewEntry The new entry. It is important that the new entry object has a valid UUID!
340 \return a pointer to the handle of the added entry.
342 virtual IEntryHandle* addEntry(const CEntry* NewEntry, IGroupHandle* Group)=0;
344 /*! Moves an entry to another group.
345 \param entry The entry which should be moved.
346 \param group The new group of the entry.*/
347 virtual void moveEntry(IEntryHandle* entry, IGroupHandle* group)=0;
350 /*! Removes a group from the database.
351 Deletes the group, all it's entries and child groups and their entries as well.
352 \param group The group which should be deleted.*/
353 virtual void deleteGroup(IGroupHandle* group)=0;
355 /*! Adds a group to the database.
356 \param Group A pointer to a CGroup object. Id and ParentId of the object are ignored.
357 \param Parent A pointer to the handle of parent of the group. Can be NULL if the group is a top-level group.
358 \return a pointer to the handle of the added group.*/
359 virtual IGroupHandle* addGroup(const CGroup* Group,IGroupHandle* Parent)=0;
362 \param Group The group which should be moved.
363 \param NewParent The new parent of the group.
364 \param Position The position of the group amongst it's new siblings. If Position is 0 the group will be prepended if it is -1 the group will be appended.*/
365 virtual void moveGroup(IGroupHandle* Group,IGroupHandle* NewParent,int Position)=0;
367 /*! Checks two given groups if one is the parent of the other.
368 \param Child The child group.
369 \param Parent The parent group.
370 \return TRUE if Parent is the parent of child, otherwise FALSE.*/
371 virtual bool isParent(IGroupHandle* parent, IGroupHandle* child)=0;
373 /*! \param index Index of the requested icon.
374 \return a reference to the pixmap of the requested icon.
376 virtual QPixmap& icon(int index)=0;
377 //! \return the number of icons provided by the database. This number can vary at runtime if the database supports custom icons.
378 virtual int numIcons()=0;
380 /*! Deletes all old invalid handles of the database.
381 Make sure that there are no pointers to those handles which are still in use before calling this function.*/
382 virtual void cleanUpHandles()=0;
384 /*! \return the number of groups in the database.*/
385 virtual int numGroups()=0;
387 /*! \return the number of entires in the database.*/
388 virtual int numEntries()=0;
390 /*! \return the number of built-in icons of the database. Each database must contain at least one built-in icon. */
391 virtual int builtinIcons()=0;
393 /*! Searches in the database for a string or regular expression.
394 \param Group The group where the search should be performed in. If Group is NULL the search will be performed in the whole database.
395 \param SearchString The searched string or a regular expression.
396 \param CaseSensitvie If this parameter is true the search will be case sensitive.
397 \param RegExp The SearchString parameter will be handled as regular expression if this parameter is true.
398 \param Recursive Defines whether the search should include subgroups of Group or not. This parameter has no effect if Group is NULL.
399 \param Fields A pointer to a six element bool array. It defines which fields are included into the search. The order is: title, username, url, password, comment, attachment description. The pointer can also be NULL, than the default pattern is used instead.
400 \return the search results as a list of pointers to the entry handles.*/
401 virtual QList<IEntryHandle*> search(IGroupHandle* Group,const QString& SearchString, bool CaseSensitve, bool RegExp,bool Recursive,bool* Fields)=0;
403 //virtual IDatabase* groupToNewDb(IGroupHandle* group)=0;
408 virtual void setCryptAlgorithm(CryptAlgorithm algo)=0;
409 virtual CryptAlgorithm cryptAlgorithm()=0;
410 virtual unsigned int keyTransfRounds()=0;
411 virtual void setKeyTransfRounds(unsigned int rounds)=0;