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 * KNewStuff Transaction
25 *
26 * Exposes different actions that can be done on an entry and means to track them to completion.
27 *
28 * To create a Transaction we should call one of the static methods that
29 * represent the different actions we can take. These will return the Transaction
30 * and we can use it to track mesages, the entries' states and eventually its
31 * completion using the @m finished signal.
32 *
33 * The Transaction will delete itself once it has finished.
34 *
35 * @since 6.0
36 */
37class KNEWSTUFFCORE_EXPORT Transaction : public QObject
38{
39 Q_OBJECT
40public:
41 ~Transaction() override;
42
43 /**
44 * Performs an install on the given @p entry from the @p engine.
45 *
46 * @param linkId specifies which of the assets we want to see installed.
47 * @returns a Transaction object that we can use to track the progress to completion
48 */
49 static Transaction *install(EngineBase *engine, const Entry &entry, int linkId = 1);
50
51 /**
52 * Uninstalls the given @p entry from the @p engine.
53 *
54 * It reverses the step done when @m install was called.
55 * @returns a Transaction object that we can use to track the progress to completion
56 */
57 static Transaction *uninstall(EngineBase *engine, const Entry &entry);
58
59 /**
60 * Adopt the @p entry from @p engine using the adoption command.
61 *
62 * For more information, see the documentation about AdoptionCommand from
63 * the knsrc file.
64 */
65 static Transaction *adopt(EngineBase *engine, const Entry &entry);
66
67 /**
68 * @returns true as soon as the Transaction is completed as it gets ready to
69 * clean itself up
70 */
71 bool isFinished() const;
72
73Q_SIGNALS:
74 void finished();
75
76 /**
77 * Provides the @p message to update our users about how the Transaction progressed
78 */
79 void signalMessage(const QString &message);
80
81 /**
82 * Informs about how the @p entry has changed
83 *
84 * @param event nature of the change
85 */
86 void signalEntryEvent(const KNSCore::Entry &entry, KNSCore::Entry::EntryEvent event);
87
88 /**
89 * Fires in the case of any critical or serious errors, such as network or API problems.
90 * @param errorCode Represents the specific type of error which has occurred
91 * @param message A human-readable message which can be shown to the end user
92 * @param metadata Any additional data which might be hepful to further work out the details of the error (see KNSCore::Entry::ErrorCode for the
93 * metadata details)
94 * @see KNSCore::Entry::ErrorCode
95 */
96 void signalErrorCode(KNSCore::ErrorCode::ErrorCode errorCode, const QString &message, const QVariant &metadata);
97
98private:
99 Transaction(const KNSCore::Entry &entry, EngineBase *engine);
100 void downloadLinkLoaded(const KNSCore::Entry &entry);
101
102 std::unique_ptr<TransactionPrivate> d;
103};
104
105}
106
107#endif
108

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