BluezQt

job.h
1 /*
2  * BluezQt - Asynchronous BlueZ wrapper library
3  *
4  * SPDX-FileCopyrightText: 2014 Alejandro Fiestas Olivares <[email protected]>
5  * SPDX-FileCopyrightText: 2014-2015 David Rosca <[email protected]>
6  *
7  * SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
8  */
9 
10 #ifndef BLUEZQT_JOB_H
11 #define BLUEZQT_JOB_H
12 
13 #include <QObject>
14 
15 #include "bluezqt_export.h"
16 
17 namespace BluezQt
18 {
19 class JobPrivate;
20 
21 /**
22  * @class BluezQt::Job job.h <BluezQt/Job>
23  *
24  * This class represents an asynchronous job performed by BluezQt,
25  * it is usually not used directly but instead it is inherit by some
26  * other class.
27  *
28  * There are two ways of using this class, one is via exec() which will block
29  * the thread until a result is fetched, the other is via connecting to the
30  * signal result()
31  *
32  * Please, think twice before using exec(), it should be used only in either
33  * unittest or cli apps.
34  *
35  * @note Job and its subclasses are meant to be used in a fire-and-forget way.
36  * Jobs will delete themselves when they finish using deleteLater().
37  *
38  * @note Even given their asynchronous nature, Jobs are still executed in the
39  * main thread, so any blocking code executed in it will block the app calling it.
40  *
41  * @see InitManagerJob
42  * @see InitObexManagerJob
43  */
44 class BLUEZQT_EXPORT Job : public QObject
45 {
46  Q_OBJECT
47  Q_PROPERTY(int error READ error)
48  Q_PROPERTY(QString errorText READ errorText)
49  Q_PROPERTY(bool running READ isRunning)
50  Q_PROPERTY(bool finished READ isFinished)
51 
52 public:
53  /**
54  * Creates a new Job object.
55  *
56  * @param parent
57  */
58  explicit Job(QObject *parent = nullptr);
59 
60  /**
61  * Destroys a Job object.
62  */
63  ~Job() override;
64 
65  /**
66  * Error type
67  *
68  * @see error() const
69  */
70  enum Error {
71  /** Indicates there is no error */
72  NoError = 0,
73  /** Subclasses should define error codes starting at this value */
74  UserDefinedError = 100
75  };
76  Q_ENUM(Error)
77 
78  /**
79  * Executes the job synchronously.
80  *
81  * This will start a nested QEventLoop internally. Nested event loop can be dangerous and
82  * can have unintended side effects, you should avoid calling exec() whenever you can and use the
83  * asynchronous interface of Job instead.
84  *
85  * Should you indeed call this method, you need to make sure that all callers are reentrant,
86  * so that events delivered by the inner event loop don't cause non-reentrant functions to be
87  * called, which usually wreaks havoc.
88  *
89  * Note that the event loop started by this method does not process user input events, which means
90  * your user interface will effectively be blocked. Other events like paint or network events are
91  * still being processed. The advantage of not processing user input events is that the chance of
92  * accidental reentrancy is greatly reduced. Still you should avoid calling this function.
93  *
94  * @warning This method blocks until the job finishes!
95  *
96  * @return true if the job has been executed without error, false otherwise
97  */
98  bool exec();
99 
100  /**
101  * Returns the error code, if there has been an error.
102  *
103  * Make sure to call this once result() has been emitted
104  *
105  * @return the error code for this job, 0 if no error.
106  */
107  int error() const;
108 
109  /**
110  * Returns the error text if there has been an error.
111  *
112  * Only call if error is not 0.
113  *
114  * This is usually some extra data associated with the error,
115  * such as a URL. Use errorString() to get a human-readable,
116  * translated message.
117  *
118  * @return a string to help understand the error
119  */
120  QString errorText() const;
121 
122  /**
123  * Returns whether the job is currently running
124  *
125  * @return true if the job is running
126  */
127  bool isRunning() const;
128 
129  /**
130  * Returns whether the job have already finished
131  *
132  * @return true if the job already finished
133  */
134  bool isFinished() const;
135 
136 public Q_SLOTS:
137  /**
138  * Starts the job asynchronously.
139  *
140  * This method will schedule doStart() to be executed in the next
141  * loop. This is done so this method returns as soon as possible.
142  *
143  * When the job is finished, result() is emitted.
144  */
145  void start();
146 
147  /**
148  * Kills the job.
149  *
150  * This method will kill the job and then call deleteLater().
151  * Only jobs started with start() can be killed.
152  *
153  * It will not emit result signal.
154  */
155  void kill();
156 
157 protected Q_SLOTS:
158  /**
159  * Implementation for start() that will be executed in next loop
160  *
161  * This slot is always called in the next loop, triggered by start().
162  *
163  * When implementing this method is important to remember that jobs
164  * are not executed on a different thread (unless done that way), so any
165  * blocking task has to be done in a different thread or process.
166  */
167  virtual void doStart() = 0;
168 
169 protected:
170  /**
171  * Sets the error code.
172  *
173  * It should be called when an error
174  * is encountered in the job, just before calling emitResult().
175  *
176  * You should define an enum of error codes,
177  * with values starting at Job::UserDefinedError, and use
178  * those. For example:
179  * @code
180  * enum ExampleErrors{
181  * InvalidFoo = UserDefinedError,
182  * BarNotFound
183  * };
184  * @endcode
185  *
186  * @param errorCode the error code
187  * @see emitResult()
188  */
189  void setError(int errorCode);
190 
191  /**
192  * Sets the error text.
193  *
194  * It should be called when an error
195  * is encountered in the job, just before calling emitResult().
196  *
197  * Provides extra information about the error that cannot be
198  * determined directly from the error code. For example, a
199  * URL or filename. This string is not normally translatable.
200  *
201  * @param errorText the error text
202  * @see emitResult(), setError()
203  */
204  void setErrorText(const QString &errorText);
205 
206  /**
207  * Utility function to emit the result signal, and suicide this job.
208  *
209  * @note Deletes this job using deleteLater().
210  * @see result() const
211  */
212  void emitResult();
213 
214  /**
215  * Implementation for emitting the result signal
216  *
217  * This function is needed to be able to emit result() signal
218  * with the job pointer's type being subclass
219  */
220  virtual void doEmitResult() = 0;
221 
222 private:
223  JobPrivate *const d_ptr;
224 
225  Q_DECLARE_PRIVATE(Job)
226 };
227 
228 } // namespace BluezQt
229 
230 #endif // BLUEZQT_JOB_H
Q_SCRIPTABLE Q_NOREPLY void start()
Error
Error type.
Definition: job.h:70
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sun Sep 25 2022 04:19:10 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.