KNewStuff

transaction.h
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#if KNEWSTUFFCORE_ENABLE_DEPRECATED_SINCE(6, 9)
44 /**
45 * Performs an install on the given @p entry from the @p engine.
46 *
47 * @param linkId specifies which of the assets we want to see installed.
48 * @returns a Transaction object that we can use to track the progress to completion
49 * @deprecated since 6.9, use installLatest or installLinkId instead
50 */
51 KNEWSTUFFCORE_DEPRECATED_VERSION(6, 9, "use installLatest or installLinkId instead")
52 static Transaction *install(EngineBase *engine, const Entry &entry, int linkId = 1);
53#endif
54
55 /**
56 * Performs an install on the given @p entry from the @p engine.
57 *
58 * @param linkId specifies which of the assets we want to see installed.
59 * @returns a Transaction object that we can use to track the progress to completion
60 * @since 6.9
61 */
62 [[nodiscard]] static Transaction *installLinkId(EngineBase *engine, const Entry &entry, quint8 linkId);
63
64 /**
65 * Performs an install of the latest version on the given @p entry from the @p engine.
66 *
67 * The latest version is determined using heuristics. If you want tight control over which offering gets installed
68 * you need to use installLinkId and manually figure out the id.
69 *
70 * @returns a Transaction object that we can use to track the progress to completion
71 * @since 6.9
72 */
73 [[nodiscard]] static Transaction *installLatest(EngineBase *engine, const Entry &entry);
74
75 /**
76 * Uninstalls the given @p entry from the @p engine.
77 *
78 * It reverses the step done when @m install was called.
79 * @returns a Transaction object that we can use to track the progress to completion
80 */
81 static Transaction *uninstall(EngineBase *engine, const Entry &entry);
82
83 /**
84 * Adopt the @p entry from @p engine using the adoption command.
85 *
86 * For more information, see the documentation about AdoptionCommand from
87 * the knsrc file.
88 */
89 static Transaction *adopt(EngineBase *engine, const Entry &entry);
90
91 /**
92 * @returns true as soon as the Transaction is completed as it gets ready to
93 * clean itself up
94 */
95 bool isFinished() const;
96
97Q_SIGNALS:
98 void finished();
99
100 /**
101 * Provides the @p message to update our users about how the Transaction progressed
102 */
103 void signalMessage(const QString &message);
104
105 /**
106 * Informs about how the @p entry has changed
107 *
108 * @param event nature of the change
109 */
111
112 /**
113 * Fires in the case of any critical or serious errors, such as network or API problems.
114 * @param errorCode Represents the specific type of error which has occurred
115 * @param message A human-readable message which can be shown to the end user
116 * @param metadata Any additional data which might be helpful to further work out the details of the error (see KNSCore::Entry::ErrorCode for the
117 * metadata details)
118 * @see KNSCore::Entry::ErrorCode
119 */
120 void signalErrorCode(KNSCore::ErrorCode::ErrorCode errorCode, const QString &message, const QVariant &metadata);
121
122private:
123 friend class TransactionPrivate;
124
125 Transaction(const KNSCore::Entry &entry, EngineBase *engine);
126 void downloadLinkLoaded(const KNSCore::Entry &entry);
127
128 std::unique_ptr<TransactionPrivate> d;
129};
130
131}
132
133#endif
KNewStuff engine.
Definition enginebase.h:56
KNewStuff data entry container.
Definition entry.h:48
KNewStuff Transaction.
Definition transaction.h:38
void signalEntryEvent(const KNSCore::Entry &entry, KNSCore::Entry::EntryEvent event)
Informs about how the entry has changed.
void signalMessage(const QString &message)
Provides the message to update our users about how the Transaction progressed.
void signalErrorCode(KNSCore::ErrorCode::ErrorCode errorCode, const QString &message, const QVariant &metadata)
Fires in the case of any critical or serious errors, such as network or API problems.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:13:34 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.