kdecore/sycoca/ksycoca.h

   1 /*  This file is part of the KDE libraries
   2  *  Copyright (C) 1999 Waldo Bastian <bastian@kde.org>
   3  *
   4  *  This library is free software; you can redistribute it and/or
   5  *  modify it under the terms of the GNU Library General Public
   6  *  License version 2 as published by the Free Software Foundation;
   7  *
   8  *  This library is distributed in the hope that it will be useful,
   9  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11  *  Library General Public License for more details.
  12  *
  13  *  You should have received a copy of the GNU Library General Public License
  14  *  along with this library; see the file COPYING.LIB.  If not, write to
  15  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16  *  Boston, MA 02110-1301, USA.
  17  **/
  18
  19 #ifndef KSYCOCA_H
  20 #define KSYCOCA_H
  21
  22 #include <kdecore_export.h>
  23 #include <ksycocatype.h>
  24
  25 #include <QtCore/QObject>
  26 #include <QtCore/QStringList>
  27
  28 class QDataStream;
  29 class KSycocaFactory;
  30 class KSycocaFactoryList;
  31 class KSycocaPrivate;
  32
  33 /**
  34  * Executable name of the kbuildsycoca program
  35  */
  36 #define KBUILDSYCOCA_EXENAME "kbuildsycoca4"
  37
  38 /**
  39  * @internal
  40  * Read-only SYstem COnfiguration CAche
  41  */
  42 class KDECORE_EXPORT KSycoca : public QObject
  43 {
  44   Q_OBJECT
  45   //Q_CLASSINFO("D-Bus Interface", "org.kde.KSycoca")
  46
  47 protected:
  48    /**
  49     * @internal
  50     * Building database
  51     */
  52    explicit KSycoca( bool /* buildDatabase */ );
  53
  54 public:
  55    /**
  56     * type of database
  57     * @see absoluteFilePath()
  58     */
  59    typedef enum { LocalDatabase, GlobalDatabase } DatabaseType;
  60
  61    /**
  62     * Read-only database
  63     */
  64    KSycoca();
  65
  66    /**
  67     * Get or create the only instance of KSycoca (read-only)
  68     */
  69    static KSycoca *self();
  70
  71    virtual ~KSycoca();
  72
  73    /**
  74     * @return the compiled-in version, i.e. the one used when writing a new ksycoca
  75     */
  76    static int version();
  77
  78    /**
  79     * @return true if the ksycoca database is available
  80     * This is usually the case, except if KDE isn't installed yet,
  81     * or before kded is started.
  82     */
  83    static bool isAvailable();
  84
  85    /**
  86     * @internal - called by factories in read-only mode
  87     * This is how factories get a stream to an entry
  88     */
  89    QDataStream *findEntry(int offset, KSycocaType &type);
  90    /**
  91     * @internal - called by factories in read-only mode
  92     */
  93    QDataStream *findFactory( KSycocaFactoryId id);
  94    /**
  95     * @internal - returns kfsstnd stored inside database
  96     */
  97    QString kfsstnd_prefixes();
  98    /**
  99     * @internal - returns absolute file path of the database
 100     *
 101     * for global database type the database is searched under
 102     * the 'services' install path.
 103     * Otherwise, the value from the environment variable KDESYCOCA
 104     * is returned if set. If not set the path is build based on
 105     * KStandardDirs cache save location.
 106     */
 107    static QString absoluteFilePath(DatabaseType type=LocalDatabase);
 108    /**
 109     * @internal - returns language stored inside database
 110     */
 111    QString language();
 112
 113    /**
 114     * @internal - returns timestamp of database
 115     *
 116     * The database contains all changes made _before_ this time and
 117     * _might_ contain changes made after that.
 118     */
 119    quint32 timeStamp();
 120
 121    /**
 122     * @internal - returns update signature of database
 123     *
 124     * Signature that keeps track of changes to
 125     * $KDEDIR/share/services/update_ksycoca
 126     *
 127     * Touching this file causes the database to be recreated
 128     * from scratch.
 129     */
 130    quint32 updateSignature();
 131
 132    /**
 133     * @internal - returns all directories with information
 134     * stored inside sycoca.
 135     */
 136    QStringList allResourceDirs();
 137
 138    /**
 139     * @internal - add a factory
 140     */
 141    void addFactory( KSycocaFactory * );
 142
 143    /**
 144     * @internal
 145     * @return true if building (i.e. if a KBuildSycoca);
 146     */
 147    virtual bool isBuilding();
 148
 149    /**
 150     * @internal - disables launching of kbuildsycoca
 151     */
 152    void disableAutoRebuild();
 153
 154    /**
 155     * When you receive a "databaseChanged" signal, you can query here if
 156     * a change has occurred in a specific resource type.
 157     * @see KStandardDirs for the various resource types.
 158     */
 159    static bool isChanged(const char *type);
 160
 161    /**
 162     * A read error occurs.
 163     */
 164    static void flagError();
 165
 166    /**
 167     * Returns read error status and clears flag.
 168     */
 169    static bool readError();
 170
 171 private Q_SLOTS:
 172    /**
 173     * internal function for receiving kded/kbuildsycoca's signal, when the sycoca file changes
 174     */
 175    void notifyDatabaseChanged(const QStringList &);
 176
 177 Q_SIGNALS:
 178    /**
 179     * Connect to this to get notified when the database changes
 180     * (Usually apps showing icons do a 'refresh' to take into account the new mimetypes)
 181     */
 182     void databaseChanged(); // KDE5 TODO: pass const QStringList& changedList here, remove isChanged()
 183
 184 protected:
 185     KSycocaFactoryList* factories();
 186
 187     // @internal used by kbuildsycoca
 188     QDataStream *m_str;
 189
 190 private:
 191     Q_DISABLE_COPY(KSycoca)
 192     friend class KSycocaPrivate;
 193     KSycocaPrivate * const d;
 194 };
 195
 196 #endif
 197