kmail/kmmsgdict.h

   1 /*
   2  * This file is part of KMail, the KDE mail client
   3  * Copyright (c)  Ronen Tzur <rtzur@shani.net>
   4  *
   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; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  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.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  *
  19  */
  20 #ifndef __KMMSGDICT
  21 #define __KMMSGDICT
  22
  23 #include <QList>
  24
  25 class KMFolder;
  26 class KMMsgBase;
  27 class KMMessage;
  28 class KMMsgDictREntry;
  29 class KMDict;
  30 class QString;
  31 class FolderStorage;
  32
  33 class KMMsgDictSingletonProvider;
  34
  35 /**
  36  * @short KMail message dictionary. Keeps location information for every
  37  * message. The message serial number is the key for the dictionary.
  38  *
  39  * The KMMsgDict singleton is used to look up at which index in which folder a
  40  * certain serial number can be found. Each folder holds a "reverse entry",
  41  * which is an array of message dict entries for that folder and persists that
  42  * to disk as an array of serial numbers, the "$folder.index.ids" file.
  43  * In effect the whole message dict is therefor persisted per folder
  44  * and restored on startup when all folder dict entries are read and re-enter
  45  * their respective entries (serial numbers) into the global dict. The code for
  46  * creating, deleting and manipulating these files is in this class, rather than
  47  * the FolderStorage class, which only holds the pointer to the reverse entry
  48  * and otherwise knows nothing of the message dict.
  49  *
  50  * @author Ronen Tzur <rtzur@shani.net>
  51  */
  52 class KMMsgDict
  53 {
  54   friend class KMMsgDictSingletonProvider;
  55   public:
  56     /** Access the globally unique MessageDict */
  57     static const KMMsgDict* instance();
  58
  59     /** Returns the folder the message represented by the serial number @p key is in
  60      * and the index in that folder at which it is stored. */
  61     void getLocation( unsigned long key, KMFolder **retFolder, int *retIndex ) const;
  62     /** Returns the folder the message represented by @p msg is in
  63       * and the index in that folder at which it is stored. */
  64     void getLocation( const KMMsgBase *msg, KMFolder **retFolder, int *retIndex ) const;
  65     /** Returns the folder the message represented by @p msg is in
  66      * and the index in that folder at which it is stored. */
  67     void getLocation( const KMMessage *msg, KMFolder **retFolder, int *retIndex ) const;
  68
  69   /** Find the message serial number for the message located at index @p index in folder
  70    * @p folder.
  71    * @return the message serial number or zero is no such message can be found */
  72     unsigned long getMsgSerNum( KMFolder *folder, int index ) const;
  73
  74   /** Convert a list of KMMsgBase pointers to a list of serial numbers */
  75     static QList<unsigned long> serNumList(QList<KMMsgBase *> msgList);
  76
  77 private:
  78  /* FIXME It would be better to do without these, they are the classes
  79   * involved in filling and maintaining the dict. The MsgList needs access
  80   * because of things it does that should be in FolderIndex, probably, which
  81   * the message list is an implementation detail of. */
  82   friend class FolderStorage;
  83   friend class KMMsgList;
  84   friend class KMFolderIndex;
  85
  86   // Access for those altering the dict, our friend classes
  87   static KMMsgDict* mutableInstance();
  88
  89   /** Insert a new message.  The message serial number is specified in
  90    * @p msgSerNum and may be zero, in which case a new serial number is
  91    * generated.  Returns the message serial number. */
  92   unsigned long insert(unsigned long msgSerNum, const KMMsgBase *msg, int index = -1);
  93
  94   /** Insert a new message.  The message serial number is taken from
  95    * the message, and passed to the other insert().  Returns the message
  96    * serial number. */
  97   unsigned long insert(const KMMsgBase *msg, int index = -1);
  98
  99   /** Set the serial number of @p msg to @p msgSerNum */
 100   void replace(unsigned long msgSerNum,
 101                const KMMsgBase *msg, int index = -1);
 102
 103   /** Removes a message. */
 104   void remove(unsigned long msgSerNum);
 105
 106   /** Removes a message, and returns its message serial number. */
 107   unsigned long remove(const KMMsgBase *msg);
 108
 109   /** Updates index for a message. */
 110   void update(const KMMsgBase *msg, int index, int newIndex);
 111
 112
 113   // ----- per folder serial number on-disk structure handling ("ids files")
 114
 115   /** Returns the name of the .folder.index.ids file. */
 116   static QString getFolderIdsLocation( const FolderStorage &folder );
 117
 118   /** Returns true if the .folder.index.ids file should not be read. */
 119   bool isFolderIdsOutdated( const FolderStorage &folder );
 120
 121   /** Reads the .folder.index.ids file.  Returns 0 on success. */
 122   int readFolderIds( FolderStorage & );
 123
 124   /** Writes the .folder.index.ids file.  Returns 0 on success. */
 125   int writeFolderIds( const FolderStorage & );
 126
 127   /** Touches the .folder.index.ids file.  Returns 0 on success. */
 128   int touchFolderIds( const FolderStorage & );
 129
 130   /** Appends the message to the .folder.index.ids file.
 131    * Returns 0 on success. */
 132   int appendToFolderIds( FolderStorage&, int index );
 133
 134   /** Returns true if the folder has a .folder.index.ids file.  */
 135   bool hasFolderIds( const FolderStorage & );
 136
 137   /** Removes the .folder.index.ids file. */
 138   bool removeFolderIds( FolderStorage & );
 139
 140   /** Opens the .folder.index.ids file, and writes the header
 141    * information at the beginning of the file. */
 142   KMMsgDictREntry *openFolderIds( const FolderStorage &, bool truncate);
 143
 144
 145   // --------- helpers ------------
 146
 147   /** delete an entry that has been assigned to a folder. Needs to be done from
 148    * inside this file, since operator delete is not available outside. */
 149   static void deleteRentry(KMMsgDictREntry *entry);
 150
 151   /** Returns the next message serial number for use. */
 152   unsigned long getNextMsgSerNum();
 153
 154   // prevent creation and deletion, we are a singleton
 155   KMMsgDict();
 156   ~KMMsgDict();
 157
 158   /** Highest message serial number we know of. */
 159   unsigned long nextMsgSerNum;
 160
 161   /** The dictionary. */
 162   KMDict *dict;
 163 };
 164
 165 #endif /* __KMMSGDICT */