File indexing completed on 2024-04-28 16:54:37
0001 /* 0002 SPDX-FileCopyrightText: 2018 Kai Uwe Broulik <kde@privat.broulik.de> 0003 0004 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL 0005 */ 0006 0007 #pragma once 0008 0009 #include <QObject> 0010 0011 #include "notificationmanager_export.h" 0012 #include "notifications.h" 0013 0014 namespace NotificationManager 0015 { 0016 class Notification; 0017 0018 class ServerInfo; 0019 class ServerPrivate; 0020 0021 /** 0022 * @short A notification DBus server 0023 * 0024 * @author Kai Uwe Broulik <kde@privat.broulik.de> 0025 **/ 0026 class NOTIFICATIONMANAGER_EXPORT Server : public QObject 0027 { 0028 Q_OBJECT 0029 0030 /** 0031 * Whether the notification service could be registered. 0032 * Call @c init() to register. 0033 */ 0034 Q_PROPERTY(bool valid READ isValid NOTIFY validChanged) 0035 0036 /** 0037 * Information about the current owner of the Notification service. 0038 * 0039 * This can be used to tell the user which application is currently 0040 * owning the service in case service registration failed. 0041 * 0042 * This is never null, even if there is no notification service running. 0043 * 0044 * @since 5.18 0045 */ 0046 Q_PROPERTY(NotificationManager::ServerInfo *currentOwner READ currentOwner CONSTANT) 0047 0048 /** 0049 * Whether notifications are currently inhibited. 0050 * 0051 * This is what is announced to other applications on the bus. 0052 * 0053 * @note This does not keep track of inhibitions on its own, 0054 * you need to calculate this yourself and update the property accordingly. 0055 */ 0056 Q_PROPERTY(bool inhibited READ inhibited WRITE setInhibited NOTIFY inhibitedChanged) 0057 0058 public: 0059 ~Server() override; 0060 0061 /** 0062 * The reason a notification was closed 0063 */ 0064 enum class CloseReason { 0065 Expired = 1, ///< The notification timed out 0066 DismissedByUser = 2, ///< The user explicitly closed or acknowledged the notification 0067 Revoked = 3, ///< The notification was revoked by the issuing app because it is no longer relevant 0068 }; 0069 Q_ENUM(CloseReason) 0070 0071 static Server &self(); 0072 0073 /** 0074 * Registers the Notification Service on DBus. 0075 * 0076 * @return true if it succeeded, false otherwise. 0077 */ 0078 bool init(); 0079 0080 /** 0081 * Whether the notification service could be registered 0082 */ 0083 bool isValid() const; 0084 0085 /** 0086 * Information about the current owner of the Notification service. 0087 * @since 5.18 0088 */ 0089 ServerInfo *currentOwner() const; 0090 0091 /** 0092 * Whether notifications are currently inhibited. 0093 * @since 5.17 0094 */ 0095 bool inhibited() const; 0096 0097 /** 0098 * Whether notifications are currently effectively inhibited. 0099 * 0100 * @note You need to keep track of inhibitions and call this 0101 * yourself when appropriate. 0102 * @since 5.17 0103 */ 0104 void setInhibited(bool inhibited); 0105 0106 /** 0107 * Whether an application requested to inhibit notifications. 0108 */ 0109 bool inhibitedByApplication() const; 0110 0111 // should we return a struct or pair or something? 0112 QStringList inhibitionApplications() const; 0113 QStringList inhibitionReasons() const; 0114 0115 /** 0116 * Remove all inhibitions. 0117 * 0118 * @note The applications are not explicitly informed about this. 0119 */ 0120 void clearInhibitions(); 0121 0122 /** 0123 * Sends a notification closed event 0124 * 0125 * @param id The notification ID 0126 * @param reason The reason why it was closed 0127 */ 0128 void closeNotification(uint id, CloseReason reason); 0129 /** 0130 * Sends an action invocation request 0131 * 0132 * @param id The notification ID 0133 * @param actionName The name of the action, e.g. "Action 1", or "default" 0134 * @param xdgActivationToken The token the application needs to send to raise itself. 0135 * @param window the window that invokes the action 0136 */ 0137 void invokeAction(uint id, const QString &actionName, const QString &xdgActivationToken, Notifications::InvokeBehavior behavior, QWindow *window); 0138 0139 /** 0140 * Convenience call to maintain ABI 0141 * 0142 * @deprecated 0143 */ 0144 void invokeAction(uint id, const QString &actionName, const QString &xdgActivationToken, Notifications::InvokeBehavior behavior) 0145 { 0146 invokeAction(id, actionName, xdgActivationToken, behavior, nullptr); 0147 } 0148 0149 /** 0150 * Sends a notification reply text 0151 * 0152 * @param dbusService The bus name of the receiving application 0153 * @param id The notification ID 0154 * @param text The reply message text 0155 * @since 5.18 0156 */ 0157 void reply(const QString &dbusService, uint id, const QString &text, Notifications::InvokeBehavior behavior); 0158 0159 /** 0160 * Adds a notification 0161 * 0162 * @note The notification isn't actually broadcast 0163 * but just emitted locally. 0164 * 0165 * @return the ID of the notification 0166 */ 0167 uint add(const Notification ¬ification); 0168 0169 Q_SIGNALS: 0170 /** 0171 * Emitted when the notification service validity changes, 0172 * because it successfully registered the service or lost 0173 * ownership of it. 0174 * @since 5.18 0175 */ 0176 void validChanged(); 0177 0178 /** 0179 * Emitted when a notification was added. 0180 * This is emitted regardless of any filtering rules or user settings. 0181 * @param notification The notification 0182 */ 0183 void notificationAdded(const Notification ¬ification); 0184 /** 0185 * Emitted when a notification is supposed to be updated 0186 * This is emitted regardless of any filtering rules or user settings. 0187 * @param replacedId The ID of the notification it replaces 0188 * @param notification The new notification to use instead 0189 */ 0190 void notificationReplaced(uint replacedId, const Notification ¬ification); 0191 /** 0192 * Emitted when a notification got removed (closed) 0193 * @param id The notification ID 0194 * @param reason The reason why it was closed 0195 */ 0196 void notificationRemoved(uint id, CloseReason reason); 0197 0198 /** 0199 * Emitted when the inhibited state changed. 0200 */ 0201 void inhibitedChanged(bool inhibited); 0202 0203 /** 0204 * Emitted when inhibitions by application have been changed. 0205 * Becomes true as soon as there is one inhibition and becomes 0206 * false again when all inhibitions have been lifted. 0207 * @since 5.17 0208 */ 0209 void inhibitedByApplicationChanged(bool inhibited); 0210 0211 /** 0212 * Emitted when the list of applications holding a notification 0213 * inhibition changes. 0214 * Normally you would only want to listen do @c inhibitedChanged 0215 */ 0216 void inhibitionApplicationsChanged(); 0217 0218 /** 0219 * Emitted when the ownership of the Notification DBus Service is lost. 0220 */ 0221 void serviceOwnershipLost(); 0222 0223 private: 0224 explicit Server(QObject *parent = nullptr); 0225 Q_DISABLE_COPY(Server) 0226 // FIXME we also need to disable move and other stuff? 0227 0228 QScopedPointer<ServerPrivate> d; 0229 }; 0230 0231 } // namespace NotificationManager