UDisksClient

UDisksClient — Utility routines for accessing the UDisks service

Functions

#define UDISKS_CHECK_VERSION()
void udisks_client_new ()
UDisksClient * udisks_client_new_finish ()
UDisksClient * udisks_client_new_sync ()
UDisksObject * udisks_client_get_object ()
UDisksObject * udisks_client_peek_object ()
GDBusObjectManager * udisks_client_get_object_manager ()
UDisksManager * udisks_client_get_manager ()
void udisks_client_settle ()
void udisks_client_queue_changed ()
GList * udisks_client_get_jobs_for_object ()
gchar * udisks_client_get_job_description ()
UDisksBlock * udisks_client_get_block_for_dev ()
GList * udisks_client_get_block_for_label ()
GList * udisks_client_get_block_for_uuid ()
UDisksBlock * udisks_client_get_block_for_drive ()
UDisksDrive * udisks_client_get_drive_for_block ()
UDisksBlock * udisks_client_get_cleartext_block ()
UDisksPartitionTable * udisks_client_get_partition_table ()
UDisksLoop * udisks_client_get_loop_for_block ()
GList * udisks_client_get_partitions ()
GList * udisks_client_get_drive_siblings ()
UDisksBlock * udisks_client_get_block_for_mdraid ()
GList * udisks_client_get_all_blocks_for_mdraid ()
GList * udisks_client_get_members_for_mdraid ()
UDisksMDRaid * udisks_client_get_mdraid_for_block ()
UDisksObjectInfo * udisks_client_get_object_info ()
void udisks_client_get_drive_info ()
gchar * udisks_client_get_partition_info ()
gchar * udisks_client_get_size_for_display ()
gchar * udisks_client_get_id_for_display ()
gchar * udisks_client_get_media_compat_for_display ()
void udisks_partition_type_info_free ()
GList * udisks_client_get_partition_type_infos ()
const gchar ** udisks_client_get_partition_table_subtypes ()
const gchar * udisks_client_get_partition_type_for_display ()
const gchar * udisks_client_get_partition_type_and_subtype_for_display ()
const gchar * udisks_client_get_partition_table_type_for_display ()
const gchar * udisks_client_get_partition_table_subtype_for_display ()

Properties

Signals

Types and Values

Object Hierarchy

    GBoxed
    ╰── UDisksPartitionTypeInfo
    GFlags
    ╰── UDisksPartitionTypeInfoFlags
    GObject
    ╰── UDisksClient

Implemented Interfaces

UDisksClient implements GInitable and GAsyncInitable.

Description

UDisksClient is used for accessing the UDisks service from a client program.

Functions

UDISKS_CHECK_VERSION()

#define             UDISKS_CHECK_VERSION(major,minor,micro)

Macro to check against the version of the libudisks2 library that is being compiled against.

Parameters

major

The major version to check for.

 

minor

the minor version to check for.

 

micro

The micro version to check for.

 

Returns

TRUE if the version of the libudisks2 header files is the same as or newer than the passed in version.


udisks_client_new ()

void
udisks_client_new (GCancellable *cancellable,
                   GAsyncReadyCallback callback,
                   gpointer user_data);

Asynchronously gets a UDisksClient. When the operation is finished, callback will be invoked in the thread-default main loop of the thread you are calling this method from.

Parameters

cancellable

A GCancellable or NULL.

 

callback

Function that will be called when the result is ready.

 

user_data

Data to pass to callback .

 

udisks_client_new_finish ()

UDisksClient *
udisks_client_new_finish (GAsyncResult *res,
                          GError **error);

Finishes an operation started with udisks_client_new().

Parameters

res

A GAsyncResult.

 

error

Return location for error or NULL.

 

Returns

A UDisksClient or NULL if error is set. Free with g_object_unref() when done with it.

[transfer full]


udisks_client_new_sync ()

UDisksClient *
udisks_client_new_sync (GCancellable *cancellable,
                        GError **error);

Synchronously gets a UDisksClient for the local system.

Parameters

cancellable

A GCancellable or NULL.

[allow-none]

error

Return location for error or NULL.

[allow-none]

Returns

A UDisksClient or NULL if error is set. Free with g_object_unref() when done with it.

[transfer full]


udisks_client_get_object ()

UDisksObject *
udisks_client_get_object (UDisksClient *client,
                          const gchar *object_path);

Convenience function for looking up an UDisksObject for object_path .

Parameters

client

A UDisksClient.

 

object_path

Object path.

 

Returns

A UDisksObject corresponding to object_path or NULL if not found. The returned object must be freed with g_object_unref().

[transfer full]


udisks_client_peek_object ()

UDisksObject *
udisks_client_peek_object (UDisksClient *client,
                           const gchar *object_path);

Like udisks_client_get_object() but doesn't increase the reference count on the returned UDisksObject.

The returned object is only valid until removed so it is only safe to use this function on the thread where client was constructed. Use udisks_client_get_object() if on another thread.

Parameters

client

A UDisksClient.

 

object_path

Object path.

 

Returns

A UDisksObject corresponding to object_path or NULL if not found.

[transfer none]


udisks_client_get_object_manager ()

GDBusObjectManager *
udisks_client_get_object_manager (UDisksClient *client);

Gets the GDBusObjectManager used by client .

Parameters

client

A UDisksClient.

 

Returns

A GDBusObjectManager. Do not free, the instance is owned by client .

[transfer none]


udisks_client_get_manager ()

UDisksManager *
udisks_client_get_manager (UDisksClient *client);

Gets the UDisksManager interface on the well-known /org/freedesktop/UDisks2/Manager object.

Parameters

client

A UDisksClient.

 

Returns

A UDisksManager or NULL if the udisksd daemon is not currently running. Do not free, the instance is owned by client .

[transfer none]


udisks_client_settle ()

void
udisks_client_settle (UDisksClient *client);

Blocks until all pending D-Bus messages have been delivered. Also emits the (rate-limited) “changed” signal if changes are currently pending.

This is useful in two situations: 1. when using synchronous method calls since e.g. D-Bus signals received while waiting for the reply are queued up and dispatched after the synchronous call ends; and

  1. when using asynchronous calls where the return value references a newly created object (such as the Manager.LoopSetup() method).

Parameters

client

A UDisksClient.

 

udisks_client_queue_changed ()

void
udisks_client_queue_changed (UDisksClient *client);

Queues up a “changed” signal and rate-limit it. See the documentation for the “changed” property for more information.

Parameters

client

A UDisksClient.

 

Since: 2.1


udisks_client_get_jobs_for_object ()

GList *
udisks_client_get_jobs_for_object (UDisksClient *client,
                                   UDisksObject *object);

Gets all the UDisksJob instances that reference object , if any.

Parameters

client

A UDisksClient.

 

object

A UDisksObject.

 

Returns

A list of UDisksJob instances. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref().

[transfer full][element-type UDisksJob]


udisks_client_get_job_description ()

gchar *
udisks_client_get_job_description (UDisksClient *client,
                                   UDisksJob *job);

Gets a human-readable and localized text string describing the operation of job .

For known job types, see the documentation for the

Job:Operation

D-Bus property.

Parameters

client

A UDisksClient.

 

job

A UDisksJob.

 

Returns

A string that should be freed with g_free().

[transfer full]


udisks_client_get_block_for_dev ()

UDisksBlock *
udisks_client_get_block_for_dev (UDisksClient *client,
                                 dev_t block_device_number);

Gets the UDisksBlock corresponding to block_device_number , if any.

Parameters

client

A UDisksClient.

 

block_device_number

A dev_t to get a UDisksBlock for.

[type guint64]

Returns

A UDisksBlock or NULL if not found.

[transfer full]


udisks_client_get_block_for_label ()

GList *
udisks_client_get_block_for_label (UDisksClient *client,
                                   const gchar *label);

Gets all the UDisksBlock instances with the given label, if any.

Parameters

client

A UDisksClient.

 

label

The label.

 

Returns

A list of UDisksBlock instances. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref().

[transfer full][element-type UDisksBlock]


udisks_client_get_block_for_uuid ()

GList *
udisks_client_get_block_for_uuid (UDisksClient *client,
                                  const gchar *uuid);

Gets all the UDisksBlock instances with the given uuid, if any.

Parameters

client

A UDisksClient.

 

uuid

The uuid.

 

Returns

A list of UDisksBlock instances. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref().

[transfer full][element-type UDisksBlock]


udisks_client_get_block_for_drive ()

UDisksBlock *
udisks_client_get_block_for_drive (UDisksClient *client,
                                   UDisksDrive *drive,
                                   gboolean get_physical);

Gets a block device corresponding to drive . The returned block device, if any, is for the whole disk drive, e.g. a partition block device is never returned.

Set get_physical to TRUE if you need a block device that you can send low-level SCSI commands with (for multipath, this returns one of the physical paths). Set it to FALSE if you need a block device that you can read/write data with (for multipath, this returns the mapped device).

Parameters

client

A UDisksClient.

 

drive

A UDisksDrive.

 

get_physical

TRUE to get a physical device, FALSE to get the logical device.

 

Returns

A UDisksBlock or NULL if the requested kind of block device is not available - use g_object_unref() to free the returned object.

[transfer full]


udisks_client_get_drive_for_block ()

UDisksDrive *
udisks_client_get_drive_for_block (UDisksClient *client,
                                   UDisksBlock *block);

Gets the UDisksDrive that block belongs to, if any.

Parameters

client

A UDisksClient.

 

block

A UDisksBlock.

 

Returns

A UDisksDrive or NULL if there is no UDisksDrive for block - free the returned object with g_object_unref().

[transfer full]


udisks_client_get_cleartext_block ()

UDisksBlock *
udisks_client_get_cleartext_block (UDisksClient *client,
                                   UDisksBlock *block);

If block is an unlocked encrypted device, gets the cleartext device.

Parameters

client

A UDisksClient.

 

block

A UDisksBlock.

 

Returns

A UDisksBlock or NULL. Free with g_object_unref() when done with it.

[transfer full]


udisks_client_get_partition_table ()

UDisksPartitionTable *
udisks_client_get_partition_table (UDisksClient *client,
                                   UDisksPartition *partition);

Gets the UDisksPartitionTable corresponding to partition .

Parameters

client

A UDisksClient.

 

partition

A UDisksPartition.

 

Returns

A UDisksPartitionTable. Free with g_object_unref().

[transfer full]


udisks_client_get_loop_for_block ()

UDisksLoop *
udisks_client_get_loop_for_block (UDisksClient *client,
                                  UDisksBlock *block);

Gets the corresponding loop interface for block .

This only works if block itself is a loop device or a partition of a loop device.

Parameters

client

A UDisksClient.

 

block

A UDisksBlock.

 

Returns

A UDisksLoop or NULL. Free with g_object_unref().

[transfer full]


udisks_client_get_partitions ()

GList *
udisks_client_get_partitions (UDisksClient *client,
                              UDisksPartitionTable *table);

Gets all partitions of table .

Parameters

client

A UDisksClient.

 

table

A UDisksPartitionTable.

 

Returns

A list of UDisksPartition instances. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref().

[transfer full][element-type UDisksPartition]


udisks_client_get_drive_siblings ()

GList *
udisks_client_get_drive_siblings (UDisksClient *client,
                                  UDisksDrive *drive);

Gets all siblings for drive .

Parameters

client

A UDisksClient

 

drive

A UDisksDrive.

 

Returns

A list of UDisksDrive instances. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref().

[transfer full][element-type UDisksDrive]

Since: 2.1


udisks_client_get_block_for_mdraid ()

UDisksBlock *
udisks_client_get_block_for_mdraid (UDisksClient *client,
                                    UDisksMDRaid *raid);

Gets the RAID device (e.g. /dev/md0) for raid .

In the case of a split-brain syndrome, it is undefined which RAID device is returned. For example this can happen if /dev/sda and /dev/sdb are components of a two-disk RAID-1 and /dev/md0 and /dev/md1 are two degraded arrays, each one using exactly one of the two devices. Use udisks_client_get_all_blocks_for_mdraid() to get all RAID devices.

Parameters

client

A UDisksClient.

 

raid

A UDisksMDRaid.

 

Returns

A UDisksBlock or NULL if no RAID device is running.

[transfer full]

Since: 2.1


udisks_client_get_all_blocks_for_mdraid ()

GList *
udisks_client_get_all_blocks_for_mdraid
                               (UDisksClient *client,
                                UDisksMDRaid *raid);

Gets all RAID devices (e.g. /dev/md0 and /dev/md1) for raid .

This is usually only useful in split-brain situations — see udisks_client_get_block_for_mdraid() for an example — and is normally used only to convey the problem in an user interface.

Parameters

client

A UDisksClient.

 

raid

A UDisksMDRaid.

 

Returns

A list of UDisksBlock instances. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref().

[transfer full][element-type UDisksBlock]

Since: 2.1


udisks_client_get_members_for_mdraid ()

GList *
udisks_client_get_members_for_mdraid (UDisksClient *client,
                                      UDisksMDRaid *raid);

Gets the physical block devices that are part of raid .

Parameters

client

A UDisksClient.

 

raid

A UDisksMDRaid.

 

Returns

A list of UDisksBlock instances. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref().

[transfer full][element-type UDisksBlock]

Since: 2.1


udisks_client_get_mdraid_for_block ()

UDisksMDRaid *
udisks_client_get_mdraid_for_block (UDisksClient *client,
                                    UDisksBlock *block);

Gets the UDisksMDRaid that block is the block device for, if any.

Parameters

client

A UDisksClient.

 

block

A UDisksBlock.

 

Returns

A UDisksMDRaid or NULL if there is no UDisksMDRaid for block or block is not a MD-RAID block device. Free the returned object with g_object_unref().

[transfer full]

Since: 2.1


udisks_client_get_object_info ()

UDisksObjectInfo *
udisks_client_get_object_info (UDisksClient *client,
                               UDisksObject *object);

Gets information about a UDisksObject instance that is suitable to present in an user interface. Information is returned in the UDisksObjectInfo object and is localized.

Parameters

client

A UDisksClient.

 

object

A UDisksObject.

 

Returns

A UDisksObjectInfo instance that should be freed with g_object_unref().

[transfer full]

Since: 2.1


udisks_client_get_drive_info ()

void
udisks_client_get_drive_info (UDisksClient *client,
                              UDisksDrive *drive,
                              gchar **out_name,
                              gchar **out_description,
                              GIcon **out_drive_icon,
                              gchar **out_media_description,
                              GIcon **out_media_icon);

udisks_client_get_drive_info has been deprecated since version 2.1 and should not be used in newly-written code.

Use udisks_client_get_object_info() instead.

Gets information about a UDisksDrive object that is suitable to present in an user interface. The returned strings are localized.

Parameters

client

A UDisksClient.

 

drive

A UDisksDrive.

 

out_name

Return location for name or NULL.

[out][allow-none]

out_description

Return location for description or NULL.

[out][allow-none]

out_drive_icon

Return location for icon representing the drive or NULL.

[out][allow-none]

out_media_description

Return location for description of the media or NULL.

[out][allow-none]

out_media_icon

Return location for icon representing the media or NULL.

[out][allow-none]

udisks_client_get_partition_info ()

gchar *
udisks_client_get_partition_info (UDisksClient *client,
                                  UDisksPartition *partition);

Gets information about partition that is suitable to present in an user interface in a single line of text.

The returned string is localized and includes things like the partition type, flags (if any) and name (if any).

Parameters

client

A UDisksClient.

 

partition

 

Returns

A string that should be freed with g_free().

[transfer full]


udisks_client_get_size_for_display ()

gchar *
udisks_client_get_size_for_display (UDisksClient *client,
                                    guint64 size,
                                    gboolean use_pow2,
                                    gboolean long_string);

Utility function to get a human-readable string that represents size .

Parameters

client

A UDisksClient.

 

size

Size in bytes

 

use_pow2

Whether power-of-two units should be used instead of power-of-ten units.

 

long_string

Whether to produce a long string.

 

Returns

A string that should be freed with g_free().

[transfer full]


udisks_client_get_id_for_display ()

gchar *
udisks_client_get_id_for_display (UDisksClient *client,
                                  const gchar *usage,
                                  const gchar *type,
                                  const gchar *version,
                                  gboolean long_string);

Gets a human readable localized string for usage , type and version .

Parameters

client

A UDisksClient.

 

usage

Usage id e.g. "filesystem" or "crypto".

 

type

Type e.g. "ext4" or "crypto_LUKS"

 

version

Version.

 

long_string

Whether to produce a long string.

 

Returns

A string that should be freed with g_free().

[transfer full]


udisks_client_get_media_compat_for_display ()

gchar *
udisks_client_get_media_compat_for_display
                               (UDisksClient *client,
                                const gchar * const *media_compat);

Gets a human-readable string of the media described by media_compat . The returned information is localized.

Parameters

client

A UDisksClient.

 

media_compat

An array of media types.

 

Returns

A string that should be freed with g_free() or NULL if unknown.

[transfer full]


udisks_partition_type_info_free ()

void
udisks_partition_type_info_free (UDisksPartitionTypeInfo *info);

Frees info .

Parameters


udisks_client_get_partition_type_infos ()

GList *
udisks_client_get_partition_type_infos
                               (UDisksClient *client,
                                const gchar *partition_table_type,
                                const gchar *partition_table_subtype);

Gets information about all known partition types for partition_table_type and partition_table_subtype .

Parameters

client

A UDisksClient.

 

partition_table_type

A partition table type e.g. 'dos' or 'gpt'.

 

partition_table_subtype

A partition table subtype or NULL to get all known types.

[allow-none]

Returns

A list of UDisksPartitionTypeInfo instances. The returned list should be freed with g_list_free() after freeing each element with udisks_partition_type_info_free().

[transfer full][element-type UDisksPartitionTypeInfo]


udisks_client_get_partition_table_subtypes ()

const gchar **
udisks_client_get_partition_table_subtypes
                               (UDisksClient *client,
                                const gchar *partition_table_type);

Gets all known subtypes for partition_table_type .

Parameters

client

A UDisksClient.

 

partition_table_type

A partition table type e.g. 'dos' or 'gpt'.

 

Returns

A NULL-terminated array of strings. Only the container should be freed with g_free().

[transfer container]


udisks_client_get_partition_type_for_display ()

const gchar *
udisks_client_get_partition_type_for_display
                               (UDisksClient *client,
                                const gchar *partition_table_type,
                                const gchar *partition_type);

Gets a human readable localized string for partiton_table_type and partition_type .

Parameters

client

A UDisksClient.

 

partition_table_type

A partitioning type e.g. 'dos' or 'gpt'.

 

partition_type

A partition type.

 

Returns

A description of partition_type or NULL if unknown.

[transfer none]


udisks_client_get_partition_type_and_subtype_for_display ()

const gchar *
udisks_client_get_partition_type_and_subtype_for_display
                               (UDisksClient *client,
                                const gchar *partition_table_type,
                                const gchar *partition_table_subtype,
                                const gchar *partition_type);

Like udisks_client_get_partition_type_for_display() but also takes the partition table subtype into account, if available. This is useful in scenarios where different subtypes is using the same partition type.

Parameters

client

A UDisksClient.

 

partition_table_type

A partitioning type e.g. 'dos' or 'gpt'.

 

partition_table_subtype

A partitioning subtype or NULL.

 

partition_type

A partition type.

 

Returns

A description of partition_type or NULL if unknown.

[transfer none]

Since: 2.1.1


udisks_client_get_partition_table_type_for_display ()

const gchar *
udisks_client_get_partition_table_type_for_display
                               (UDisksClient *client,
                                const gchar *partition_table_type);

Gets a human readable localized string for partition_table_type .

Parameters

client

A UDisksClient.

 

partition_table_type

A partition table type e.g. 'dos' or 'gpt'.

 

Returns

A description of partition_table_type or NULL.

[transfer none]


udisks_client_get_partition_table_subtype_for_display ()

const gchar *
udisks_client_get_partition_table_subtype_for_display
                               (UDisksClient *client,
                                const gchar *partition_table_type,
                                const gchar *partition_table_subtype);

Gets a human readable localized string for partition_table_type and partition_table_subtype .

Parameters

client

A UDisksClient.

 

partition_table_type

A partition table type e.g. 'dos' or 'gpt'.

 

partition_table_subtype

A partition table type e.g. 'dos' or 'gpt'.

 

Returns

A description of partition_table_type and partition_table_subtype or NULL.

[transfer none]

Types and Values

UDISKS_MAJOR_VERSION

#define             UDISKS_MAJOR_VERSION

The major version of the libudisks2 header files.


UDISKS_MINOR_VERSION

#define             UDISKS_MINOR_VERSION

The minor version of the libudisks2 header files.


UDISKS_MICRO_VERSION

#define             UDISKS_MICRO_VERSION

The micro version of the libudisks2 header files.


UDisksClient

typedef struct _UDisksClient UDisksClient;

The UDisksClient structure contains only private data and should only be accessed using the provided API.


UDisksPartitionTypeInfo

typedef struct {
  const gchar                  *table_type;
  const gchar                  *table_subtype;
  const gchar                  *type;
  UDisksPartitionTypeInfoFlags  flags;
} UDisksPartitionTypeInfo;

Detailed information about a partition type.

table_subtype is used to break the set of partition types for table_type into a logical subsets. It is typically only used in user interfaces where the partition type is selected.

This struct may grow in the future without it being considered an ABI break.

Members

const gchar *table_type;

A partition table type e.g. 'dos' or 'gpt'

 

const gchar *table_subtype;

A partition table sub-type.

 

const gchar *type;

A partition type.

 

UDisksPartitionTypeInfoFlags flags;

Flags from the UDisksPartitionTypeInfoFlags enumeration.

 

enum UDisksPartitionTypeInfoFlags

Flags describing a partition type.

Members

UDISKS_PARTITION_TYPE_INFO_FLAGS_NONE

No flags set.

 

UDISKS_PARTITION_TYPE_INFO_FLAGS_SWAP

Partition type is used for swap.

 

UDISKS_PARTITION_TYPE_INFO_FLAGS_RAID

Partition type is used for RAID/LVM or similar.

 

UDISKS_PARTITION_TYPE_INFO_FLAGS_HIDDEN

Partition type indicates the partition is hidden (e.g. 'dos' type 0x1b "Hidden W95 FAT32"). Note that this is not the same as user-toggleable attributs/flags for a partition.

 

UDISKS_PARTITION_TYPE_INFO_FLAGS_CREATE_ONLY

Partition type can only be used when creating a partition and e.g. should not be selectable in a "change partition type" user interface (e.g. 'dos' type 0x05, 0x0f and 0x85 for extended partitions).

 

UDISKS_PARTITION_TYPE_INFO_FLAGS_SYSTEM

Partition type indicates the partition is part of the system / bootloader (e.g. 'dos' types 0xee, 0xff, 'gpt' types for 'EFI System partition' and 'BIOS Boot partition').

 

Property Details

The “manager” property

  “manager”                  UDisksManager *

The UDisksManager interface on the well-known /org/freedesktop/UDisks2/Manager object

Flags: Read


The “object-manager” property

  “object-manager”           GDBusObjectManager *

The GDBusObjectManager used by the UDisksClient instance.

Flags: Read

Signal Details

The “changed” signal

void
user_function (UDisksClient *client,
               gpointer      user_data)

This signal is emitted either when an object or interface is added or removed a when property has changed. Additionally, multiple received signals are coalesced into a single signal that is rate-limited to fire at most every 100ms.

Note that calling udisks_client_settle() will cause this signal to fire if any changes are outstanding.

For greater detail, connect to the “object-added”, “object-removed”, “interface-added”, “interface-removed”, “interface-proxy-properties-changed” and signals on the “object-manager” object.

Parameters

client

A UDisksClient.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last