File indexing completed on 2024-06-16 04:50:17
0001 /* 0002 SPDX-FileCopyrightText: 2008 Volker Krause <vkrause@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #pragma once 0008 0009 #include "akonadicore_export.h" 0010 0011 #include <QMetaType> 0012 #include <QObject> 0013 0014 namespace Akonadi 0015 { 0016 class ServerManagerPrivate; 0017 0018 /** 0019 * @short Provides methods to control the Akonadi server process. 0020 * 0021 * Asynchronous, low-level control of the Akonadi server. 0022 * Akonadi::Control provides a synchronous interface to some of the methods in here. 0023 * 0024 * @author Volker Krause <vkrause@kde.org> 0025 * @see Akonadi::Control 0026 * @since 4.2 0027 */ 0028 class AKONADICORE_EXPORT ServerManager : public QObject 0029 { 0030 Q_OBJECT 0031 public: 0032 /** 0033 * Enum for the various states the server can be in. 0034 * @since 4.5 0035 */ 0036 enum State { 0037 NotRunning, ///< Server is not running, could be no one started it yet or it failed to start. 0038 Starting, ///< Server was started but is not yet running. 0039 Running, ///< Server is running and operational. 0040 Stopping, ///< Server is shutting down. 0041 Broken, ///< Server is not operational and an error has been detected. 0042 Upgrading ///< Server is performing a database upgrade as part of a new startup. 0043 }; 0044 0045 /** 0046 * Starts the server. This method returns immediately and does not wait 0047 * until the server is actually up and running. 0048 * @return @c true if the start was possible (which not necessarily means 0049 * the server is really running though) and @c false if an immediate error occurred. 0050 * @see Akonadi::Control::start() 0051 */ 0052 static bool start(); 0053 0054 /** 0055 * Stops the server. This methods returns immediately after the shutdown 0056 * command has been send and does not wait until the server is actually 0057 * shut down. 0058 * @return @c true if the shutdown command was sent successfully, @c false 0059 * otherwise 0060 */ 0061 static bool stop(); 0062 0063 /** 0064 * Shows the Akonadi self test dialog, which tests Akonadi for various problems 0065 * and reports these to the user if. 0066 * @param parent the parent widget for the dialog 0067 */ 0068 static void showSelfTestDialog(QWidget *parent); 0069 0070 /** 0071 * Checks if the server is available currently. For more detailed status information 0072 * see state(). 0073 * @see state() 0074 */ 0075 [[nodiscard]] static bool isRunning(); 0076 0077 /** 0078 * Returns the state of the server. 0079 * @since 4.5 0080 */ 0081 [[nodiscard]] static State state(); 0082 0083 /** 0084 * Returns the reason why the Server is broken, if known. 0085 * 0086 * If state() is @p Broken, then you can use this method to obtain a more 0087 * detailed description of the problem and present it to users. Note that 0088 * the message can be empty if the reason is not known. 0089 * 0090 * @since 5.6 0091 */ 0092 [[nodiscard]] static QString brokenReason(); 0093 0094 /** 0095 * Returns the identifier of the Akonadi instance we are connected to. This is usually 0096 * an empty string (representing the default instance), unless you have explicitly set 0097 * the AKONADI_INSTANCE environment variable to connect to a different one. 0098 * @since 4.10 0099 */ 0100 [[nodiscard]] static QString instanceIdentifier(); 0101 0102 /** 0103 * Returns @c true if we are connected to a non-default Akonadi server instance. 0104 * @since 4.10 0105 */ 0106 [[nodiscard]] static bool hasInstanceIdentifier(); 0107 0108 /** 0109 * Types of known D-Bus services. 0110 * @since 4.10 0111 */ 0112 enum ServiceType { 0113 Server, 0114 Control, 0115 ControlLock, 0116 UpgradeIndicator, 0117 }; 0118 0119 /** 0120 * Returns the namespaced D-Bus service name for @p serviceType. 0121 * Use this rather the raw service name strings in order to support usage of a non-default 0122 * instance of the Akonadi server. 0123 * @param serviceType the service type for which to return the D-Bus name 0124 * @since 4.10 0125 */ 0126 static QString serviceName(ServiceType serviceType); 0127 0128 /** 0129 * Known agent types. 0130 * @since 4.10 0131 */ 0132 enum ServiceAgentType { 0133 Agent, 0134 Resource, 0135 Preprocessor, 0136 }; 0137 0138 /** 0139 * Returns the namespaced D-Bus service name for an agent of type @p agentType with agent 0140 * identifier @p identifier. 0141 * @param agentType the agent type to use for D-Bus base name 0142 * @param identifier the agent identifier to include in the D-Bus name 0143 * @since 4.10 0144 */ 0145 [[nodiscard]] static QString agentServiceName(ServiceAgentType agentType, const QString &identifier); 0146 0147 /** 0148 * Adds the multi-instance namespace to @p string if required (with '_' as separator). 0149 * Use whenever a multi-instance safe name is required (configfiles, identifiers, ...). 0150 * @param string the string to adapt 0151 * @since 4.10 0152 */ 0153 [[nodiscard]] static QString addNamespace(const QString &string); 0154 0155 /** 0156 * Returns the singleton instance of this class, for connecting to its 0157 * signals 0158 */ 0159 static ServerManager *self(); 0160 0161 enum OpenMode { 0162 ReadOnly, 0163 ReadWrite, 0164 }; 0165 /** 0166 * Returns absolute path to akonadiserverrc file with Akonadi server 0167 * configuration. 0168 */ 0169 [[nodiscard]] static QString serverConfigFilePath(OpenMode openMode); 0170 0171 /** 0172 * Returns absolute path to configuration file of an agent identified by 0173 * given @p identifier. 0174 */ 0175 [[nodiscard]] static QString agentConfigFilePath(const QString &identifier); 0176 0177 /** 0178 * Returns current Akonadi database generation identifier 0179 * 0180 * Generation is guaranteed to never change unless as long as the database 0181 * backend is not removed and re-created. In such case it is guaranteed that 0182 * the new generation number will be higher than the previous one. 0183 * 0184 * Generation can be used by applications to detect when Akonadi database 0185 * has been recreated and thus some of the configuration (for example 0186 * collection IDs stored in a config file) must be invalidated. 0187 * 0188 * @note Note that the generation number is only available if the server 0189 * is running. If this function is called before the server starts it will 0190 * return 0. 0191 * 0192 * @since 5.4 0193 */ 0194 [[nodiscard]] static uint generation(); 0195 0196 Q_SIGNALS: 0197 /** 0198 * Emitted whenever the server becomes fully operational. 0199 */ 0200 void started(); 0201 0202 /** 0203 * Emitted whenever the server becomes unavailable. 0204 */ 0205 void stopped(); 0206 0207 /** 0208 * Emitted whenever the server state changes. 0209 * @param state the new server state 0210 * @since 4.5 0211 */ 0212 void stateChanged(Akonadi::ServerManager::State state); 0213 0214 private: 0215 /// @cond PRIVATE 0216 friend class ServerManagerPrivate; 0217 ServerManager(ServerManagerPrivate *dd); 0218 ServerManagerPrivate *const d; 0219 /// @endcond 0220 }; 0221 0222 } 0223 0224 Q_DECLARE_METATYPE(Akonadi::ServerManager::State)