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