1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1999 Waldo Bastian <bastian@kde.org>
4 SPDX-FileCopyrightText: 2005-2008 David Faure <faure@kde.org>
5 SPDX-FileCopyrightText: 2020 Harald Sitter <sitter@kde.org>
6
7 SPDX-License-Identifier: LGPL-2.0-only
8*/
9
10#ifndef KSYCOCA_H
11#define KSYCOCA_H
12
13#include <kservice_export.h>
14#include <ksycocatype.h>
15
16#include <QObject>
17#include <QStringList>
18
19class QDataStream;
20class KSycocaFactory;
21class KSycocaFactoryList;
22class KSycocaPrivate;
23
24/**
25 * Executable name of the kbuildsycoca program
26 */
27#define KBUILDSYCOCA_EXENAME "kbuildsycoca6"
28
29/**
30 * @internal
31 * Read-only SYstem COnfiguration CAche
32 */
33class KSERVICE_EXPORT KSycoca : public QObject
34{
35 Q_OBJECT
36 // Q_CLASSINFO("D-Bus Interface", "org.kde.KSycoca")
37
38protected:
39 /**
40 * @internal
41 * Building database
42 */
43 explicit KSycoca(bool /* buildDatabase */);
44
45public:
46 /**
47 * Read-only database
48 */
49 KSycoca();
50
51 /**
52 * Get or create the only instance of KSycoca (read-only)
53 */
54 static KSycoca *self();
55
56 ~KSycoca() override;
57
58 /**
59 * @return the compiled-in version, i.e. the one used when writing a new ksycoca
60 */
61 static int version();
62
63 /**
64 * @return true if the ksycoca database is available
65 * This is usually the case, except if KDE isn't installed yet,
66 * or before kded is started.
67 */
68 static bool isAvailable();
69
70 /**
71 * @internal - called by factories in read-only mode
72 * This is how factories get a stream to an entry
73 */
74 QDataStream *findEntry(int offset, KSycocaType &type); // KF6: make it private
75 /**
76 * @internal - called by factories in read-only mode
77 * Returns stream(), but positioned for reading this factory, 0 on error.
78 */
79 QDataStream *findFactory(KSycocaFactoryId id); // KF6: make it private
80
81 /**
82 * @internal - returns absolute file path of the database
83 *
84 * For the global database type, the database is searched under
85 * the 'share/ksycoca' install path.
86 * Otherwise, the value from the environment variable KDESYCOCA
87 * is returned if set. If not set the path is built based on
88 * QStandardPaths cache save location, typically ~/.cache on Unix.
89 *
90 * Since 5.15, the filename includes language and a sha1 of the directories
91 * in GenericDataLocation, i.e. the directories with the desktop files.
92 * This allows to have one database per setup, when using different install prefixes
93 * or when switching languages.
94 */
95 static QString absoluteFilePath();
96
97 /**
98 * @internal - returns all directories with information
99 * stored inside sycoca.
100 */
101 QStringList allResourceDirs(); // KF6: make it private
102
103 /**
104 * @internal - add a factory
105 */
106 void addFactory(KSycocaFactory *); // KF6: make it private
107
108 /**
109 * @internal
110 * @return true if building (i.e. if a KBuildSycoca);
111 */
112 virtual bool isBuilding();
113
114 /**
115 * Disables automatic rebuilding of the cache on service file changes.
116 * Be extremely careful when using this. Only threads that definitely have no use for
117 * automatic reloading should use this. Specifically shared runner threads (as seen in
118 * the threadweaver framework) can avoid claiming persistent resources this way
119 * (e.g. inotify instances on Linux).
120 */
121 static void disableAutoRebuild();
122
123 /**
124 * A read error occurs.
125 * @internal
126 */
127 static void flagError();
128
129 /**
130 * Ensures the ksycoca database is up to date.
131 * If the database was modified by another process, close it, so the next use reopens it.
132 * If the desktop files have been modified more recently than the database, update it.
133 *
134 * Update the sycoca file from the files on disk (e.g. desktop files or mimeapps.list).
135 * You don't normally have to call this because the next use of KSycoca
136 * (e.g. via KMimeTypeTrader, KService etc.) will notice that the sycoca
137 * database is out of date, by looking a directory modification times.
138 * In addition, in a full KDE session, kded monitors directories to detect changes.
139 *
140 * This is however useful for GUIs that allow to create a new desktop file
141 * and then want to ensure it is available immediately in KSycoca.
142 * This is also useful after modifying a mimeapps.list file.
143 *
144 * KBuildSycocaProgressDialog can also be used instead of this method, in GUI apps.
145 *
146 * @since 5.15
147 */
148 void ensureCacheValid(); // Warning for kservice code: this can delete all the factories.
149
150 /**
151 * Sets up a minimal applications.menu file in the appropriate location.
152 * This is useful when writing unit tests that interact with KService.
153 *
154 * You should call QStandardPaths::setTestModeEnabled(true) before calling this.
155 *
156 * @since 6.0
157 */
158 static void setupTestMenu();
159
160 /**
161 * Connect to this to get notified when the database changes.
162 *
163 * Example: after creating a .desktop file in KOpenWithDialog, it
164 * must wait until kbuildsycoca6 finishes until the KService::Ptr is available.
165 * Other examples: anything that displays a list of apps or plugins to the user
166 * and which is always visible (otherwise querying sycoca before showing
167 * could be enough).
168 */
169 Q_SIGNAL void databaseChanged();
170
171protected:
172 // @internal used by kbuildsycoca
173 KSycocaFactoryList *factories();
174
175 // @internal used by factories and kbuildsycoca
176 QDataStream *&stream();
177 friend class KSycocaFactory;
178 friend class KSycocaDict;
179
180 void connectNotify(const QMetaMethod &signal) override;
181
182private:
183 /**
184 * Clear all caches related to ksycoca contents.
185 * @internal only used by kded and kbuildsycoca.
186 */
187 static void clearCaches();
188
189 KSERVICE_NO_EXPORT bool needsRebuild();
190
191 friend class KBuildSycoca;
192 friend class Kded;
193 friend class KSycocaPrivate;
194 friend class KSycocaXdgDirsTest;
195
196 Q_DISABLE_COPY(KSycoca)
197 KSycocaPrivate *const d;
198};
199
200#endif
201

source code of kservice/src/sycoca/ksycoca.h