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
18namespace KNSCore
19{
20class EngineBase;
21class 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 */
40class KNEWSTUFFCORE_EXPORT Transaction : public QObject
41{
42 Q_OBJECT
43public:
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
103Q_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
134private:
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

source code of knewstuff/src/core/transaction.h