org.freedesktop.UDisks2.Job: UDisks Reference Manual

org.freedesktop.UDisks2.Job

org.freedesktop.UDisks2.Job — Long-running tasks

Methods

Cancel (IN  a{sv} options);

Signals

Completed (b success,
           s message);

Properties

Operation        readable   s
Progress         readable   d
ProgressValid    readable   b
Bytes            readable   t
Rate             readable   t
StartTime        readable   t
ExpectedEndTime  readable   t
Objects          readable   ao
StartedByUID     readable   u
Cancelable       readable   b

Description

Some operations may take a long time (hours) to complete, that is, to actually send the D-Bus reply message back. One example of such an operation is the Format() method that is used to format a block device.

When such operations are initiated, a job object implementing this interface may be created so the progress can be tracked by the caller (and also other observers).

The object(s) that a job affects (such as block devices or drives) can be determined by looking at the "Objects" property. Among other things, this can be used to draw a spinner in the user interface next to e.g. an icon for the drive or device in question.

The "Operation" property is used to convey the type of job currently in progress.

The user id of the user who started the job is set in the "StartedByUID" property.

A job may convey how much progress has been made, see the "Progress" and "ProgressValid" properties.

When a job completes, the "Completed" signal is emitted.

A job may or may not be cancelable, see the "Cancelable" property. To cancel a job use the Cancel() method. This will cause the job to complete (with success set to FALSE) and the D-Bus method used to initiate the operation to return, usually returning the org.freedesktop.UDisks2.Error.Cancelled error. Once cancellation is requested it may take some time before the job is actually completed as there might be ongoing I/O.

Method Details

The Cancel() method

Cancel (IN  a{sv} options);

Cancels the job. Fails with the org.freedesktop.UDisks2.Error.Failed error if "Cancelable" is FALSE.

IN a{sv} options:

Options (currently unused except for standard options).

Signal Details

The "Completed" signal

Completed (b success,
           s message);

Emitted when a job completes.

`b success`:	If `TRUE`, the job completed successfully.
`s message`:	A message describing the completion of the job, e.g. an error message.

Property Details

The "Operation" property

Operation  readable   s

The type of the operation that the job represents.

Known job operation types include:

ata-smart-selftest	SMART self-test operation.
drive-eject	Ejecting the medium from a drive.
encrypted-unlock	Unlocking encrypted device.
encrypted-lock	Locking encrypted device.
encrypted-modify	Modifying encrypted device.
encrypted-resize	Resizing encrypted device.
encrypted-convert	Converting encrypted device.
swapspace-start	Starting swapspace.
swapspace-stop	Stopping swapspace.
swapspace-modify	Modifying swapspace.
filesystem-mount	Mounting a filesystem.
filesystem-unmount	Unmounting a filesystem.
filesystem-modify	Modifying a filesystem.
filesystem-resize	Resizing a filesystem.
format-erase	Erasing a device.
format-mkfs	Creating a filesystem.
loop-setup	Setting up a loop device.
partition-modify	Modifying a partition.
partition-delete	Deleting a partition.
partition-create	Creating a partition.
cleanup	Cleaning up devices that were removed without being properly unmounted or shut down.
ata-secure-erase	ATA Secure Erase.
ata-enhanced-secure-erase	ATA Enhanced Secure Erase.
md-raid-stop	Stopping a RAID Array.
md-raid-start	Starting a RAID Array.
md-raid-fault-device	Marking device in RAID Array as faulty.
md-raid-remove-device	Removing device from RAID Array.
md-raid-create	Create a RAID Array.
nvme-selftest	NVMe device self-test operation.
nvme-sanitize	NVMe sanitize operation.
nvme-format-ns	NVMe format namespace operation.

The udisks_client_get_job_description() function can be used to get a localized human readable description.

The "Progress" property

Progress  readable   d

How much progress has been made. Values are in the range 0 to 1.

Do not use unless "ProgressValid" is TRUE.

The "ProgressValid" property

ProgressValid  readable   b

Set to TRUE if the "Progress" is valid.

The "Bytes" property

Bytes  readable   t

since: 2.0.0 If the job involves processing a known number of bytes (for example, erasing a disk), this property contains the total number of bytes to process. If not, the value of this property is zero.

The intent of this property is for user interfaces to convey information such as “123 GB of 1.0 TB completed”.

The "Rate" property

Rate  readable   t

since: 2.0.0 If the job involves processing a number of bytes (for example, erasing) and the rate at which the processing takes place is known, this property contains the rate (measured in bytes per second). Otherwise the value of this property is zero.

The intent of this property is for user interfaces to convey information such as “110 MB/sec”.

The "StartTime" property

StartTime  readable   t

The point in time (micro-seconds since the Unix Epoch) that the job was started.

The "ExpectedEndTime" property

ExpectedEndTime  readable   t

The expected point in time (micro-seconds since the Unix Epoch) that the job will complete or 0 if unknown.

The "Objects" property

Objects  readable   ao

The objects that the job is related to, if any.

The "StartedByUID" property

StartedByUID  readable   u

The id of the user who started the job or 0 if started by root or not through udisks.

The "Cancelable" property

Cancelable  readable   b

Whether the job can be canceled.