org.freedesktop.UDisks2.Drive

org.freedesktop.UDisks2.Drive — Disk drives

Methods

Eject            (IN  a{sv} options);
SetConfiguration (IN  a{sv} value,
                  IN  a{sv} options);
PowerOff         (IN  a{sv} options);

Properties

Vendor                 readable   s
Model                  readable   s
Revision               readable   s
Serial                 readable   s
WWN                    readable   s
Id                     readable   s
Configuration          readable   a{sv}
Media                  readable   s
MediaCompatibility     readable   as
MediaRemovable         readable   b
MediaAvailable         readable   b
MediaChangeDetected    readable   b
Size                   readable   t
TimeDetected           readable   t
TimeMediaDetected      readable   t
Optical                readable   b
OpticalBlank           readable   b
OpticalNumTracks       readable   u
OpticalNumAudioTracks  readable   u
OpticalNumDataTracks   readable   u
OpticalNumSessions     readable   u
RotationRate           readable   i
ConnectionBus          readable   s
Seat                   readable   s
Removable              readable   b
Ejectable              readable   b
SortKey                readable   s
CanPowerOff            readable   b
SiblingId              readable   s

Description

This interface is used to represent both hard disks and disk drives (with or without removable media).

This interface should not to be confused with the org.freedesktop.UDisks2.Block interface that is used for low-level block devices the OS knows about. For example, if /dev/sda and /dev/sdb are block devices for two paths to the same drive, there will be only one org.freedesktop.UDisks2.Drive object but two org.freedesktop.UDisks2.Block objects.

Method Details

The Eject() method

Eject (IN  a{sv} options);

Ejects media from the drive. This is only meaningful to do on drives with removable media.

There are not a lot of guarantees associated with this method so it should only be called in response to an user action.

On some hardware the media may be physically ejected while on other hardware may simply eject the disc. On some hardware it may not do anything physical but it may cause e.g. a display on the hardware to show e.g. It is now safe to remove the device.

IN a{sv} options:

Options (currently unused except for standard options).


The SetConfiguration() method

SetConfiguration (IN  a{sv} value,
                  IN  a{sv} options);

Sets the configuration for the drive. This will store the configuration in the file-system and also apply it to the drive.

See the "Configuration" property for details about valid values and the location of the configuration file that value will be written to.

IN a{sv} value:

The configuration value to set.

IN a{sv} options:

Options (currently unused except for standard options).


The PowerOff() method

PowerOff (IN  a{sv} options);

Arranges for the drive to be safely removed and powered off. On the OS side this includes ensuring that no process is using the drive, then requesting that in-flight buffers and caches are committed to stable storage. The exact steps for powering off the drive depends on the drive itself and the interconnect used. For drives connected through USB, the effect is that the USB device will be deconfigured followed by disabling the upstream hub port it is connected to.

Note that as some physical devices contain multiple drives (for example 4-in-1 flash card reader USB devices) powering off one drive may affect other drives. Applications can examine the "SiblingId" property to determine such relationships.

There are not a lot of guarantees associated with this method so it should only be called in response to an user action. Usually the effect is that the drive disappears as if it was unplugged.

This method only works if the "CanPowerOff" property is set to TRUE.

IN a{sv} options:

Options (currently unused except for standard options).

Since 2.0.0

Property Details

The "Vendor" property

Vendor  readable   s

A name for the vendor of the drive or blank if unknown.


The "Model" property

Model  readable   s

A name for the model of the drive or blank if unknown.


The "Revision" property

Revision  readable   s

Firmware Revision or blank if unknown.


The "Serial" property

Serial  readable   s

Serial number of the drive or blank if unknown.


The "WWN" property

WWN  readable   s

The World Wide Name of the drive or blank if unknown.

In case of NVMe drives please refer to namespace-level WWN properties.


The "Id" property

Id  readable   s

A unique and persistent identifier for the device or blank if no such identifier is available.

This identifier is guaranteed to not include the slash character '/' (U+002F SOLIDUS) which means it can be used as a filename.

Examples: ST32000542AS-6XW00W51, HITACHI-HTS723232A7A364-E3834563KRG2HN, INTEL-SSDSA2MH080G1GC-CVEM842101HD080DGN.


The "Configuration" property

Configuration  readable   a{sv}

A set of configuration directives that are applied to the drive when it is connected (e.g. at start-up, hotplug or resume).

This is an dict of items with the following known keys:

ata-pm-standby (type 'i')

The spindown timeout for ATA drives (See ATA command STANDBY).

ata-apm-level (type 'i')

The APM level for ATA drives (See ATA command SET FEATURES, sub-commands 0x05 and 0x85).

ata-aam-level (type 'i')

The AAM level for ATA drives (See ATA command SET FEATURES, sub-commands 0x42 and 0xc2).

ata-write-cache-enabled (type 'b')

Whether the write-cache is enabled (See ATA command SET FEATURES, sub-commands 0x82 and 0x02). Since 2.1.

ata-read-lookahead-enabled (type 'b')

Whether the read look-ahead is enabled (See ATA command SET FEATURES, sub-commands 0x55 and 0xaa). Since 2.1.7.

The contents of this property is read from the configuration file /etc/udisks2/IDENTIFIER.conf where IDENTIFIER is the value of the "Id" property. See udisks(8) for the file format of this file.

Use the SetConfiguration() method to change the value of this property.


The "Media" property

Media  readable   s

The kind of media currently in the drive or blank if unknown.

See the "MediaCompatibility" property for known values.


The "MediaCompatibility" property

MediaCompatibility  readable   as

The physical kind of media the drive uses or the type of the drive or blank if unknown. Known values include

thumb

The device is a thumb-drive with non-removable media (e.g. a USB stick)

flash

Flash Card

flash_cf

CompactFlash

flash_ms

MemoryStick

flash_sm

SmartMedia

flash_sd

Secure Digital

flash_sdhc

Secure Digital High Capacity

flash_sdxc

Secure Digital eXtended Capacity

flash_sdio

Secure Digital Input Output

flash_sd_combo

Secure Digital Input Output combo card with storage and I/O functionality

flash_mmc

MultiMediaCard

floppy

Floppy Disk

floppy_zip

Zip Disk

floppy_jaz

Jaz Disk

optical

Optical Disc

optical_cd

Compact Disc

optical_cd_r

Compact Disc Recordable

optical_cd_rw

Compact Disc Rewritable

optical_dvd

Digital Versatile Disc

optical_dvd_r

DVD-R

optical_dvd_rw

DVD-RW

optical_dvd_ram

DVD-RAM

optical_dvd_plus_r

DVD+R

optical_dvd_plus_rw

DVD+RW

optical_dvd_plus_r_dl

DVD+R Dual Layer

optical_dvd_plus_rw_dl

DVD+RW Dual Layer

optical_bd

Blu-ray Disc

optical_bd_r

Blu-ray Recordable

optical_bd_re

Blu-ray Rewritable

optical_hddvd

HD-DVD

optical_hddvd_r

HD-DVD Recordable

optical_hddvd_rw

HD-DVD Rewritable

optical_mo

Magneto Optical

optical_mrw

Can read Mount Rainer media

optical_mrw_w

Can write Mount Rainer media


The "MediaRemovable" property

MediaRemovable  readable   b

Whether the media can be removed from the drive.

Note that this may be overridden from what the hardware reports - for example, USB thumb drives often report that they are using removable media while in fact the media is not removable.


The "MediaAvailable" property

MediaAvailable  readable   b

Set to FALSE if no medium is available.

This is always TRUE if "MediaChangeDetected" is FALSE.


The "MediaChangeDetected" property

MediaChangeDetected  readable   b

Set to TRUE only if media changes are detected.

Media changes are detected on all modern disk drives through either polling or an asynchronous notification mechanism. The only known disk drives that cannot report media changes are PC floppy drives.


The "Size" property

Size  readable   t

The size of the drive (or the media currently in the drive).

In case of NVMe this value indicates the total NVM capacity that is accessible by the NVMe controller. This is always 0 if "MediaChangeDetected" is FALSE.


The "TimeDetected" property

TimeDetected  readable   t

The time the drive was first detected.

This is expressed in micro-seconds since the Epoch Jan 1, 1970 0:00 UTC.


The "TimeMediaDetected" property

TimeMediaDetected  readable   t

The earliest time media was last detected or 0 if media is not available.

This is expressed in micro-seconds since the Epoch Jan 1, 1970 0:00 UTC.


The "Optical" property

Optical  readable   b

TRUE if the drive contains an optical disc.


The "OpticalBlank" property

OpticalBlank  readable   b

TRUE if the disc is blank.

This is only valid if the property "Optical" is TRUE.


The "OpticalNumTracks" property

OpticalNumTracks  readable   u

The number of tracks.

This is only valid if the property "Optical" is TRUE.


The "OpticalNumAudioTracks" property

OpticalNumAudioTracks  readable   u

The number of audio tracks.

This is only valid if the property "Optical" is TRUE.


The "OpticalNumDataTracks" property

OpticalNumDataTracks  readable   u

The number of data tracks.

This is only valid if the property "Optical" is TRUE.


The "OpticalNumSessions" property

OpticalNumSessions  readable   u

The number of sessions.

This is only valid if the property "Optical" is TRUE.


The "RotationRate" property

RotationRate  readable   i

The rotational rate of the drive.

  • -1 if known to be rotating media but rotation rate isn't known

  • 0 if known to be non-rotating media

  • the rotation rate in rounds per minute otherwise


The "ConnectionBus" property

ConnectionBus  readable   s

The physical connection bus used for the drive as seen by the user. This is typically used to draw a USB or Firewire emblem on top of an icon in an user interface.

Note that this property has nothing to do with the low-level command-set used (such as ATA-8) or what low-level connection bus (such as SATA, eSATA, PATA, SAS2 etc) is used.

Known values include:

usb

Connected via USB

sdio

Connected via SDHC or SDIO controller (including eMMC).

ieee1394

Connected via Firewire


The "Seat" property

Seat  readable   s

A string identifying what seat the drive is plugged into, if any.


The "Removable" property

Removable  readable   b

A hint whether the drive and/or its media is considered removable by the user.

This includes drives with removable media (cf. the "MediaRemovable" property), Flash media such as SD cards and drives on hotpluggable buses such as USB or Firewire (cf. the "ConnectionBus" property).

Note that this is only a guess.


The "Ejectable" property

Ejectable  readable   b

Whether the media can be ejected from the drive or the drive accepts an eject command to switch its state so it displays e.g. a "Safe To Remove" message to the user.

Note that this is only a guess.


The "SortKey" property

SortKey  readable   s

A string that can be used for sorting drive objects.


The "CanPowerOff" property

CanPowerOff  readable   b

since: 2.0.0 Whether the drive can be safely removed / powered off. See the PowerOff() method for more information.

See udisks(8) for how to influence the value of this property.


The "SiblingId" property

SiblingId  readable   s

since: 2.0.0 An opaque token that, if non-blank, is used to group drives that are part of the same physical device.