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)