1 /*
2  * Copyright (C) 2013  Daniel Vrátil <dvratil@redhat.com>
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
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  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with this library; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
17  *
18  */
19 
20 #ifndef KTP_ABSTRACTLOGGERPLUGIN_H
21 #define KTP_ABSTRACTLOGGERPLUGIN_H
22 
23 #include <QtCore/QObject>
24 
25 #include <KTp/ktpcommoninternals_export.h>
26 
27 #include <TelepathyQt/Types>
28 
29 namespace KTp {
30 
31 class PendingLoggerDates;
32 class PendingLoggerLogs;
33 class PendingLoggerEntities;
34 class PendingLoggerSearch;
35 class LogEntity;
36 
37 /**
38  * @brief An interface for all KTp Logger plugins
39  *
40  * @since 0.7
41  * @author Daniel Vrátil <dvratil@redhat.com>
42  */
43 class KTPCOMMONINTERNALS_EXPORT AbstractLoggerPlugin : public QObject
44 {
45     Q_OBJECT
46 
47   public:
48     /**
49      * Constructor.
50      */
51     explicit AbstractLoggerPlugin(QObject *parent = nullptr);
52 
53     /**
54      * Destructor.
55      */
56     ~AbstractLoggerPlugin() override;
57 
58     /**
59      * Queries all available plugins that handle given @p account for list of dates
60      * with logs of user's chat with @p entity.
61      *
62      * @param account Account to query
63      * @param entity Entity
64      * @return Returns KTp::PendingLoggerDates operation that will emit finished()
65      *         signal when all backends are finished.
66      */
67     virtual KTp::PendingLoggerDates* queryDates(const Tp::AccountPtr &account,
68                                                 const KTp::LogEntity &entity) = 0;
69 
70     /**
71      * Queries all available plugins that handle given @p account for list of
72      * logs of chats with @p entity.
73      *
74      * @param account Account to query
75      * @param entity Entity whose logs should be retrieved
76      * @param date Specific date for which to retrieve logs
77      * @return Returns KTp::PendingLoggerLogs operation that will emit finished()
78      *         signal when all backends are finished.
79      */
80     virtual KTp::PendingLoggerLogs* queryLogs(const Tp::AccountPtr &account,
81                                               const KTp::LogEntity &entity,
82                                               const QDate &date) = 0;
83 
84     /**
85      * Queries all available plugins that handle given @p account for list of
86      * entities for which they have conversation logs.
87      *
88      * @param account Account to query
89      * @return Returns KTp::PendingLoggerEntities operation that will emit finished()
90      *         signal when all backends are finished.
91      */
92     virtual KTp::PendingLoggerEntities* queryEntities(const Tp::AccountPtr &account) = 0;
93 
94     /**
95      * Returnes whether plugin handles logs for given @p account.
96      *
97      * For example, a dedicated Facebook plugin will handle only accounts that
98      * represent Facebook accounts, therefore it makes no sense to query it for
99      * logs from GTalk account for instance.
100      *
101      * By default this method returns true, which means that plugin supports any
102      * kind of account.
103      */
104     virtual bool handlesAccount(const Tp::AccountPtr &account);
105 
106     /**
107      * Removes all logs for given @p account from all available plugins that
108      * handle it.
109      *
110      * @param account Account of which to remove logs
111      */
112     virtual void clearAccountLogs(const Tp::AccountPtr &account) = 0;
113 
114     /**
115      * Removes all logs for given @p entity from all available plugins that
116      * handle the @p account.
117      *
118      * @param account Account to query
119      * @param entity Entity whose logs to remove
120      */
121     virtual void clearContactLogs(const Tp::AccountPtr &account,
122                                   const KTp::LogEntity &entity) = 0;
123 
124     /**
125      * Searches all logs for given @p term.
126      *
127      * @param term Term to search
128      * @return Returns KTp::PendingLoggerSearch operation that will emit finished()
129      *         when all results are available
130      */
131     virtual KTp::PendingLoggerSearch* search(const QString &term) = 0;
132 
133     /**
134      * Sets a new Tp::AccountManager to be used by the plugin.
135      *
136      * The @p accountManager is expected to be in ready state.
137      *
138      * @param accountManager An Tp::AccountManager in the ready state.
139      */
140     virtual void setAccountManager(const Tp::AccountManagerPtr &accountManager);
141 
142     /**
143      * Returns the set Tp::AccountManager or an empty pointer if none was set.
144      */
145     virtual Tp::AccountManagerPtr accountManager() const;
146 
147     /**
148      * Checks whether there are any logs for given @p account and @p contact.
149      *
150      * For easy use this method is synchronous and can block for a while in case
151      * of a slower plugin.
152      *
153      * @param account Account to query
154      * @param contact Contact to query
155      * @return Returns whether there are any logs for given person
156      */
157     virtual bool logsExist(const Tp::AccountPtr &account, const KTp::LogEntity &contact) = 0;
158 
159   private:
160     class Private;
161     Private * const d;
162 };
163 
164 } // namespace KTp
165 
166 #endif // KTP_ABSTRACTLOGGERPLUGIN_H
167