|
libschauer
0.0.1
Qt based library to access the Docker HTTP API.
|
Base class for all jobs. More...
#include <sjob.h>

Public Types | |
| enum | { NoError = 0, KilledJobError = 1, UserDefinedError = 100 } |
| Error codes. More... | |
| enum | Capability { NoCapabilities = 0x0000, Killable = 0x0001, Suspendable = 0x0002 } |
| Job capabilities. More... | |
| enum | Unit { Bytes = 0, Files, Directories, Items } |
| Describes the unit used in the methods that handle reporting the job progress info. More... | |
Properties | |
| Schauer::SJob::Capabilities | capabilities |
| Capabilities of this job. More... | |
| int | error |
| Error code. More... | |
| QString | errorString |
| Human-readable error message. More... | |
| QString | errorText |
| Additional error text. More... | |
| ulong | percent |
| Overall progress of the job. More... | |
Public Member Functions | |
| SJob (QObject *parent=nullptr) | |
| Stores a combination of Capability values. More... | |
| ~SJob () override | |
| Desconstructs the SJob obejct. More... | |
| Capabilities | capabilities () const |
| Returns the capabilities of this job. More... | |
| int | error () const |
| Returns the error code, if there has been an error. More... | |
| virtual QString | errorString () const |
| A human-readable error message. More... | |
| QString | errorText () const |
| Returns the error text if there has been an error. More... | |
| bool | exec () |
| Executes the job synchronously. More... | |
| bool | isAutoDelete () const |
Returns true if this job automatically deletes itself once the job is finished. More... | |
| bool | isFinishedNotificationHidden () const |
| bool | isSuspended () const |
Returns true if the job was suspended with the suspend() call. More... | |
| unsigned long | percent () const |
| Returns the overall progress of this job. More... | |
| Q_SCRIPTABLE qulonglong | processedAmount (Unit unit) const |
| Returns the processed amount of a given unit for this job. More... | |
| void | setAutoDelete (bool autodelete) |
| Sets the auto-delete property of the job. More... | |
| void | setFinishedNotificationHidden (bool hide=true) |
| virtual Q_SCRIPTABLE void | start ()=0 |
| Starts the job asynchronously. More... | |
| Q_SCRIPTABLE qulonglong | totalAmount (Unit unit) const |
| Returns the total amount of a given unit for this job. More... | |
Public Slots | |
| bool | kill (Schauer::SJob::KillVerbosity verbosity=Quietly) |
| Aborts this job. More... | |
| bool | resume () |
| Resumes this job. More... | |
| bool | suspend () |
| Suspends this job. More... | |
Signals | |
| void | description (Schauer::SJob *job, const QString &title, const QPair< QString, QString > &field1=QPair< QString, QString >(), const QPair< QString, QString > &field2=QPair< QString, QString >()) |
| Emitted to display general description of this job. More... | |
| void | finished (Schauer::SJob *job) |
| Emitted when the job is finished, in any case. More... | |
| void | infoMessage (Schauer::SJob *job, const QString &plain, const QString &rich=QString()) |
| Emitted to display state information about this job. More... | |
| void | percent (Schauer::SJob *job, unsigned long percent) |
| Progress signal showing the overall progress of the job This is valid for any kind of job, and allows using a a progress bar very easily. More... | |
| void | percentChanged (Schauer::SJob *job, unsigned long percent) |
| Progress signal showing the overall progress of the job This is valid for any kind of job, and allows using a a progress bar very easily. More... | |
| void | processedAmount (Schauer::SJob *job, SJob::Unit unit, qulonglong amount) |
| Regularly emitted to show the progress of this job by giving the current amount. More... | |
| void | processedAmountChanged (Schauer::SJob *job, SJob::Unit unit, qulonglong amount) |
| Regularly emitted to show the progress of this job by giving the current amount. More... | |
| void | processedSize (Schauer::SJob *job, qulonglong size) |
| Regularly emitted to show the progress of this job (current data size in bytes for transfers, entries listed, etc.). More... | |
| void | result (Schauer::SJob *job) |
| Emitted when the job is finished (except when killed with SJob::Quietly). More... | |
| void | resumed (Schauer::SJob *job) |
| Emitted when the job is resumed. More... | |
| void | speed (Schauer::SJob *job, unsigned long speed) |
| Emitted to display information about the speed of this job. More... | |
| void | suspended (Schauer::SJob *job) |
| Emitted when the job is suspended. More... | |
| void | totalAmount (Schauer::SJob *job, SJob::Unit unit, qulonglong amount) |
| Emitted when we know the amount the job will have to process. More... | |
| void | totalAmountChanged (Schauer::SJob *job, SJob::Unit unit, qulonglong amount) |
| Emitted when we know the amount the job will have to process. More... | |
| void | totalSize (Schauer::SJob *job, qulonglong size) |
| Emitted when we know the size of this job (data size in bytes for transfers, number of entries for listings, etc). More... | |
| void | warning (Schauer::SJob *job, const QString &plain, const QString &rich=QString()) |
| Emitted to display a warning about this job. More... | |
Protected Member Functions | |
| virtual bool | doKill () |
| Aborts this job quietly. More... | |
| virtual bool | doResume () |
| Resumes this job. More... | |
| virtual bool | doSuspend () |
| Suspends this job. More... | |
| void | emitPercent (qulonglong processedAmount, qulonglong totalAmount) |
| Utility function for inherited jobs. More... | |
| void | emitResult () |
| Utility function to emit the result signal, and suicide this job. More... | |
| void | emitSpeed (unsigned long speed) |
| Utility function for inherited jobs. More... | |
| bool | isFinished () const |
Returns true if the job has been finished and has emitted the finished() signal. More... | |
| void | setCapabilities (Capabilities capabilities) |
| Sets the capabilities for this job. More... | |
| void | setError (int errorCode) |
| Sets the error code. More... | |
| void | setErrorText (const QString &errorText) |
| Sets the error text. More... | |
| void | setPercent (unsigned long percentage) |
| Sets the overall progress of the job. More... | |
| void | setProcessedAmount (Unit unit, qulonglong amount) |
| Sets the processed size. More... | |
| void | setProgressUnit (Unit unit) |
| Sets the unit that will be used internally to calculate the progress percentage. More... | |
| void | setTotalAmount (Unit unit, qulonglong amount) |
| Sets the total size. More... | |
Base class for all jobs.
This is a reimplementation of KJob from KDE Frameworks’ KCoreAddons, it is meant for platforms and systems where KJob is not available. If KCoreAddons are available, you should build libschauer with cmake -DWITH_KDE to use the original KJob implementation.
| anonymous enum |
Job capabilities.
| Enumerator | |
|---|---|
| NoCapabilities | None of the capabilities exist. |
| Killable | The job can be killed. |
| Suspendable | The job can be suspended. |
| enum Schauer::SJob::Unit |
Describes the unit used in the methods that handle reporting the job progress info.
|
read |
Capabilities of this job.
|
read |
Error code.
This property holds the error code after finishing the job. If no error has occured, the error code will be 0.
|
read |
Human-readable error message.
This property holds a translated, human-readable description of the error.
|
read |
Additional error text.
This property holds additional error text, usually some extra data associated with the error, such as a URL.
|
read |
|
explicit |
Stores a combination of Capability values.
Constructs a new SJob object with the given parent.
|
override |
Desconstructs the SJob obejct.
| Capabilities Schauer::SJob::capabilities | ( | ) | const |
Returns the capabilities of this job.
|
signal |
Emitted to display general description of this job.
A description has a title and tow optional fields which can be used to complete the description.
Examples of titles are “Copying“, “Creating resource”, etc. The fields of the description can be “Source“ with an URL and “Destination“ with an URL for a “Copying“ description.
| job | the job that emitted the signal |
| title | the general description of the job |
| field1 | first field (localized name and value) |
| field2 | second field (localized name and value) |
|
protectedvirtual |
Aborts this job quietly.
This simply kills the job, no error reporting or job deletion should be involved. The default implementation does nothing and returns false.
true if the operation is supported and succeedd, false otherwise.
|
protectedvirtual |
|
protectedvirtual |
Suspends this job.
The default implementation does nothing and returns false.
true if the operation is supported and succeeded, false otherwise.
|
protected |
Utility function for inherited jobs.
Emits the percent signal if bigger than previous value, after calculating it from the parameters.
| processedAmount | the processed amount |
| totalAmount | the total amount |
|
protected |
Utility function to emit the result signal, and suicide this job.
It first notifies the observers to hide the progress for this job using the finished() signal.
|
protected |
Utility function for inherited jobs.
Emits the speed signal and starts the timer for removing that info
| speed | the speed in bytes/s |
| int Schauer::SJob::error | ( | ) | const |
Returns the error code, if there has been an error.
Only call this method from the slot connected to result(). If there has been no error, 0 will be returned.
|
virtual |
A human-readable error message.
This provides a translated, human-readable description of the error. Only call if error is not 0.
Subclasses should implement this to create a translated error message from the error code and error text. For example:
Reimplemented in Schauer::Job.
| QString Schauer::SJob::errorText | ( | ) | const |
Returns the error text if there has been an error.
Only call if error is not 0.
This is usually some extra data associated with the error, such as a URL. Use errorString() to get a human-readable, translated message.
| bool SJob::exec | ( | ) |
Executes the job synchronously.
This will start a nested QEventLoop internally. Nested event loop can be dangerous and can have unintended side effects, you should avoid calling exec() whenever you can and use the asynchronous interface of SJob instead.
Should you indeed call this method, you need to make sure that all callers are reentrant, so that events delivered by the inner event loop don't cause non-reentrant functions to be called, which usually wreaks havoc.
Note that the event loop started by this method does not process user input events, which means your user interface will effectively be blocked. Other events like paint or network events are still being processed. The advantage of not processing user input events is that the chance of accidental reentrance is greatly reduced. Still you should avoid calling this function.
Returns if the job has been executed without eror, false otherwise.
|
signal |
Emitted when the job is finished, in any case.
It is used to notify observers that the job is terminated and that progress can be hidden.
In general, to be notified of a job’s completion, client code should connect to result() rather than finished(), so that kill(Quietly) is indeed quiet. However if you store a list of jobs and they might get killed silently, then you must connect to this instead of result(), to avoid dangling pointers in your list.
| job | the job that emitted this signal |
|
signal |
Emitted to display state information about this job.
Examples of message are “Resolving host”, “Connecting to host...”, etc.
| job | the job that emitted this signal |
| plain | the info message |
| rich | the rich text version of the message, or QString() if none is available |
| bool SJob::isAutoDelete | ( | ) | const |
Returns true if this job automatically deletes itself once the job is finished.
|
protected |
Returns true if the job has been finished and has emitted the finished() signal.
| bool SJob::isFinishedNotificationHidden | ( | ) | const |
Whether to not show a finished notification when a job's finished signal is emitted.
| bool SJob::isSuspended | ( | ) | const |
|
slot |
Aborts this job.
This kills and deletes the job.
| verbosity | if equals to EmitResult, job will emit signal result() and ask uiserver to close the progress window. verbosity is set to EmitResult for subjobs. Whether applications should call with Quietly or EmitResult depends on whether they rely on result being emitted or not. Please notice that if verbosity is set to Quietly, signal result will NOT be emitted. |
true if the operation is supported and succeeded, false otherwise | unsigned long Schauer::SJob::percent | ( | ) | const |
Returns the overall progress of this job.
|
signal |
Progress signal showing the overall progress of the job This is valid for any kind of job, and allows using a a progress bar very easily.
| job | the job that emitted this signal |
| percent | the percentage |
|
signal |
Progress signal showing the overall progress of the job This is valid for any kind of job, and allows using a a progress bar very easily.
| job | the job that emitted this signal |
| percent | the percentage |
| qulonglong SJob::processedAmount | ( | Unit | unit | ) | const |
Returns the processed amount of a given unit for this job.
| unit | the unit of the requested amount |
|
signal |
Regularly emitted to show the progress of this job by giving the current amount.
The unit of this amount is sent too. It can be emitted several times if the job manages several different units.
| job | the job that emitted this signal |
| unit | the unit of the processed amount |
| amount | the processed amount |
|
signal |
Regularly emitted to show the progress of this job by giving the current amount.
The unit of this amount is sent too. It can be emitted several times if the job manages several different units.
| job | the job that emitted this signal |
| unit | the unit of the processed amount |
| amount | the processed amount |
|
signal |
Regularly emitted to show the progress of this job (current data size in bytes for transfers, entries listed, etc.).
| job | the job that emitted this signal |
| size | the processed size |
|
signal |
Emitted when the job is finished (except when killed with SJob::Quietly).
Use error() to know if the job was finished with error.
Please connect to this signal instead of finished.
| job | the job that emitted this signal |
|
slot |
Resumes this job.
true if the operation is supported and succeeded, false otherwise.
|
signal |
Emitted when the job is resumed.
| job | the job that emitted this signal |
| void SJob::setAutoDelete | ( | bool | autodelete | ) |
Sets the auto-delete property of the job.
If autodelete is set to false the job will not delete itself once it is finished.
The default for any SJob is to automatically delete itself.
|
protected |
Sets the capabilities for this job.
| capabilities | the capabilities supported by this job |
|
protected |
Sets the error code.
It should be called when an error is encountered in the job, just before calling emitResult().
You should define an (anonymous) enum of error codes, with values starting at SJob::UserDefinedError, and use those. For example:
| errorCode |
|
protected |
Sets the error text.
It should be called when an error is encountered in the job, just before calling emitResult().
Provides extra information about the error that cannot be determined directly from the error code. For example, a URL or filename. This string is not normally translatable.
| errorText | the error text |
| void SJob::setFinishedNotificationHidden | ( | bool | hide = true | ) |
This method can be used to indicate to classes listening to signals from a job that they should ideally show a progress bar, but not a finished notification.
For example when opening a remote URL, a job will emit the progress of the download, which can be used to show a progress dialog or a Plasma notification, then when the job is done it'll emit e.g. the finished signal. Showing the user the progress dialog is useful, however the dialog/notification about the download being finished isn't of much interest, because the user can see the application that invoked the job opening the actual file that was downloaded.
|
protected |
Sets the overall progress of the job.
The percent() signal is emitted if the value changed.
The job takes care of this if you call setProcessedAmount in Bytes (or the unit set by setProgressUnit). This method allows you to set your own progress, as an alternative.
| percentage | the new overall progress |
|
protected |
Sets the processed size.
The processedAmount() and percent() signals are emitted if the values changed. The percent() signal is emitted only for the progress unit.
| unit | the unit of the new processed amount |
| amount | the new processed amount |
|
protected |
Sets the unit that will be used internally to calculate the progress percentage.
The default progress unit is Bytes.
| unit | the unit that will be used |
|
protected |
Sets the total size.
The totalSize() and percent() signals are emitted if the values changed. The percent() signal is emitted only for the progress unit.
| unit | the unit of the new total amount |
| amount | the new total amount |
|
signal |
Emitted to display information about the speed of this job.
| job | the job that emitted this signal |
| speed | the speed in bytes/s |
|
pure virtual |
Starts the job asynchronously.
When the job is finished, result() is emitted.
This is the method all subclasses need to implement. It should setup and trigger the workload of the job. It should not do any work itself. This includes all signals and terminating the job, e.g. by emitResult(). The workload, which could be another method of the subclass, is to be triggered using the event loop, e.g. by code like:
Implemented in Schauer::CreateExecInstanceJob, Schauer::StartExecInstanceJob, Schauer::ListContainersJob, Schauer::RemoveContainerJob, Schauer::ListImagesJob, Schauer::StartContainerJob, Schauer::CreateContainerJob, Schauer::StopContainerJob, and Schauer::GetVersionJob.
|
slot |
Suspends this job.
The job should be kept in a state in which it is possible to resume it.
true if the operation is supported and succeeded, false otherwise
|
signal |
Emitted when the job is suspended.
| job | the job that emitted this signal |
| qulonglong SJob::totalAmount | ( | Unit | unit | ) | const |
Returns the total amount of a given unit for this job.
| unit | the unit of the requested amount |
|
signal |
Emitted when we know the amount the job will have to process.
The unit of this amount is sent too. It can be emitted several times if the job manages several different units.
| job | the job that emitted this signal |
| unit | the unit of the total amount |
| amount | the total amount |
|
signal |
Emitted when we know the amount the job will have to process.
The unit of this amount is sent too. It can be emitted several times if the job manages several different units.
| job | the job that emitted this signal |
| unit | the unit of the total amount |
| amount | the total amount |
|
signal |
Emitted when we know the size of this job (data size in bytes for transfers, number of entries for listings, etc).
| job | the job that emitted this signal |
| size | the total size |
|
signal |
Emitted to display a warning about this job.
| job | the job that emitted this signal |
| plain | the warning message |
| rich | the rich text version of the message, or QString() is none is available |
1.8.14