1 | /* |
2 | SPDX-FileCopyrightText: 2023 Aleix Pol Gonzalez <aleixpol@kde.org> |
3 | |
4 | SPDX-License-Identifier: LGPL-2.1-or-later |
5 | */ |
6 | |
7 | #ifndef KNEWSTUFF3_TRANSACTION_H |
8 | #define KNEWSTUFF3_TRANSACTION_H |
9 | |
10 | #include <QObject> |
11 | #include <memory> |
12 | |
13 | #include "entry.h" |
14 | #include "errorcode.h" |
15 | |
16 | #include "knewstuffcore_export.h" |
17 | |
18 | namespace KNSCore |
19 | { |
20 | class EngineBase; |
21 | class TransactionPrivate; |
22 | |
23 | /*! |
24 | * \class KNSCore::Transaction |
25 | * \inmodule KNewStuffCore |
26 | * |
27 | * \brief KNewStuff Transaction. |
28 | * |
29 | * Exposes different actions that can be done on an entry and means to track them to completion. |
30 | * |
31 | * To create a Transaction we should call one of the static methods that |
32 | * represent the different actions we can take. These will return the Transaction |
33 | * and we can use it to track mesages, the entries' states and eventually its |
34 | * completion using the \c finished signal. |
35 | * |
36 | * The Transaction will delete itself once it has finished. |
37 | * |
38 | * \since 6.0 |
39 | */ |
40 | class KNEWSTUFFCORE_EXPORT Transaction : public QObject |
41 | { |
42 | Q_OBJECT |
43 | public: |
44 | ~Transaction() override; |
45 | |
46 | #if KNEWSTUFFCORE_ENABLE_DEPRECATED_SINCE(6, 9) |
47 | /*! |
48 | * Performs an install on the given \a entry from the \a engine. |
49 | * |
50 | * \a linkId specifies which of the assets we want to see installed. |
51 | * |
52 | * Returns a Transaction object that we can use to track the progress to completion |
53 | * \deprecated[6.9] |
54 | * Use installLatest or installLinkId instead |
55 | */ |
56 | KNEWSTUFFCORE_DEPRECATED_VERSION(6, 9, "use installLatest or installLinkId instead" ) |
57 | static Transaction *install(EngineBase *engine, const Entry &entry, int linkId = 1); |
58 | #endif |
59 | |
60 | /*! |
61 | * Performs an install on the given \a entry from the \a engine. |
62 | * |
63 | * \a linkId specifies which of the assets we want to see installed. |
64 | * |
65 | * Returns a Transaction object that we can use to track the progress to completion |
66 | * \since 6.9 |
67 | */ |
68 | [[nodiscard]] static Transaction *installLinkId(EngineBase *engine, const Entry &entry, quint8 linkId); |
69 | |
70 | /*! |
71 | * Performs an install of the latest version on the given \a entry from the \a engine. |
72 | * |
73 | * The latest version is determined using heuristics. If you want tight control over which offering gets installed |
74 | * you need to use installLinkId and manually figure out the id. |
75 | * |
76 | * Returns a Transaction object that we can use to track the progress to completion |
77 | * \since 6.9 |
78 | */ |
79 | [[nodiscard]] static Transaction *installLatest(EngineBase *engine, const Entry &entry); |
80 | |
81 | /*! |
82 | * Uninstalls the given \a entry from the \a engine. |
83 | * |
84 | * It reverses the step done when install() was called. |
85 | * Returns a Transaction object that we can use to track the progress to completion |
86 | */ |
87 | static Transaction *uninstall(EngineBase *engine, const Entry &entry); |
88 | |
89 | /*! |
90 | * Adopt the \a entry from \a engine using the adoption command. |
91 | * |
92 | * For more information, see the documentation about AdoptionCommand from |
93 | * the knsrc file. |
94 | */ |
95 | static Transaction *adopt(EngineBase *engine, const Entry &entry); |
96 | |
97 | /*! |
98 | * Returns true as soon as the Transaction is completed as it gets ready to |
99 | * clean itself up |
100 | */ |
101 | bool isFinished() const; |
102 | |
103 | Q_SIGNALS: |
104 | void finished(); |
105 | |
106 | /*! |
107 | * Provides the \a message to update our users about how the Transaction progressed |
108 | */ |
109 | void signalMessage(const QString &message); |
110 | |
111 | /*! |
112 | * Informs about how the \a entry has changed |
113 | * |
114 | * \a event nature of the change |
115 | * |
116 | */ |
117 | void signalEntryEvent(const KNSCore::Entry &entry, KNSCore::Entry::EntryEvent event); |
118 | |
119 | /*! |
120 | * Fires in the case of any critical or serious errors, such as network or API problems. |
121 | * |
122 | * \a errorCode Represents the specific type of error which has occurred |
123 | * |
124 | * \a message A human-readable message which can be shown to the end user |
125 | * |
126 | * \a metadata Any additional data which might be helpful to further work |
127 | * out the details of the error (see KNSCore::Entry::ErrorCode for the |
128 | * metadata details) |
129 | * |
130 | * \sa KNSCore::ErrorCode |
131 | */ |
132 | void signalErrorCode(KNSCore::ErrorCode::ErrorCode errorCode, const QString &message, const QVariant &metadata); |
133 | |
134 | private: |
135 | friend class TransactionPrivate; |
136 | |
137 | Transaction(const KNSCore::Entry &entry, EngineBase *engine); |
138 | void downloadLinkLoaded(const KNSCore::Entry &entry); |
139 | |
140 | std::unique_ptr<TransactionPrivate> d; |
141 | }; |
142 | |
143 | } |
144 | |
145 | #endif |
146 | |