From b52154d41fe1bf5abcafd90316827454d4c6dc11 Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Thu, 20 Sep 2012 10:37:05 -0400 Subject: [PATCH] Slightly rework UDisksObjectInfo docs Also include the UDisksObject instance in the struct. Signed-off-by: David Zeuthen --- udisks/udisksclient.c | 188 +++----------------------------------------------- udisks/udisksclient.h | 27 ++++++-- 2 files changed, 30 insertions(+), 185 deletions(-) diff --git a/udisks/udisksclient.c b/udisks/udisksclient.c index 862eb78..27a7b86 100644 --- a/udisks/udisksclient.c +++ b/udisks/udisksclient.c @@ -2405,11 +2405,15 @@ G_DEFINE_BOXED_TYPE (UDisksPartitionTypeInfo, udisks_partition_type_info, udisks /* ---------------------------------------------------------------------------------------------------- */ static UDisksObjectInfo * -udisks_object_info_new (void) +udisks_object_info_new (UDisksObject *object) { UDisksObjectInfo *ret; + + g_return_val_if_fail (object == NULL || UDISKS_IS_OBJECT (object), NULL); + ret = g_slice_new0 (UDisksObjectInfo); ret->ref_count = 1; + ret->object = object != NULL ? g_object_ref (object) : NULL; return ret; } @@ -2440,6 +2444,7 @@ udisks_object_info_unref (UDisksObjectInfo *info) { if (g_atomic_int_dec_and_test (&info->ref_count)) { + g_clear_object (&info->object); g_free (info->name); g_free (info->description); g_clear_object (&info->icon); @@ -2856,183 +2861,6 @@ udisks_client_get_object_info_for_drive (UDisksClient *client, * present in an user interface. Information is returned in the * #UDisksObjectInfo object and is localized. * - * The - * HintName - * and/or - * HintIconName - * propreties on associated #UDisksBlock interfaces associated with @object may influence - * the result (either directly or indirectly). - * - * The returned data is best described by example: - * - * - * - * - * Interfaces on @object - * @name - * @description - * @icon - * @media_description - * @media_icon - * - * - * - * - * #UDisksDrive: USB Thumb Drive - * Kingston DataTraveler 2.0 - * 4.0 GB Thumb Drive - * media-removable - * %NULL - * %NULL - * - * - * #UDisksDrive: Internal System Disk (Hard Disk) - * ST3320620AS - * 320 GB Hard Disk - * drive-harddisk - * %NULL - * %NULL - * - * - * #UDisksDrive: Internal System Disk (Solid State) - * INTEL SSDSA2MH080G1GC - * 80 GB Disk - * drive-harddisk - * %NULL - * %NULL - * - * - * #UDisksDrive: Optical Drive (empty) - * LITE-ON DVDRW SOHW-812S - * CD/DVD Drive - * drive-optical - * %NULL - * %NULL - * - * - * #UDisksDrive: Optical Drive (with CD-ROM data disc) - * LITE-ON DVDRW SOHW-812S - * CD/DVD Drive - * drive-optical - * CD-ROM Disc - * media-optical-cd-rom - * - * - * #UDisksDrive: Optical Drive (with mixed disc) - * LITE-ON DVDRW SOHW-812S - * CD/DVD Drive - * drive-optical - * Audio/Data CD-ROM Disc - * media-optical-cd-rom - * - * - * #UDisksDrive: Optical Drive (with audio disc) - * LITE-ON DVDRW SOHW-812S - * CD/DVD Drive - * drive-optical - * Audio Disc - * media-optical-cd-audio - * - * - * #UDisksDrive: Optical Drive (with DVD-ROM disc) - * LITE-ON DVDRW SOHW-812S - * CD/DVD Drive - * drive-optical - * DVD-ROM Disc - * media-optical-dvd-rom - * - * - * #UDisksDrive: Optical Drive (with blank DVD-R disc) - * LITE-ON DVDRW SOHW-812S - * CD/DVD Drive - * drive-optical - * Blank DVD-R Disc - * media-optical-dvd-r - * - * - * #UDisksDrive: External USB Hard Disk - * WD 2500JB External - * 250 GB Hard Disk - * drive-harddisk-usb - * %NULL - * %NULL - * - * - * #UDisksDrive: USB Compact Flash Reader (without media) - * BELKIN USB 2 HS-CF - * Compact Flash Drive - * drive-removable-media-flash-cf - * %NULL - * %NULL - * - * - * #UDisksDrive: USB Compact Flash Reader (with media) - * BELKIN USB 2 HS-CF - * Compact Flash Drive - * drive-removable-media-flash-cf - * Compact Flash media - * media-flash-cf - * - * - * #UDisksBlock whole disk with associated #UDisksDrive - * (same as drive) - * (same as drive) - * (same as drive) - * (same as drive) - * (same as drive) - * - * - * #UDisksBlock partition with associated #UDisksDrive - * (same as drive) - * Partition N of (drive description) - * (same as drive) - * (same as drive) - * (same as drive) - * - * - * #UDisksBlock without associated #UDisksDrive - * The value of the PreferredDevice property, e.g. /dev/vg_thinkpad/lv_root - * 42.0 MB Block Device - * drive-removable-media - * %NULL - * %NULL - * - * - * #UDisksBlock for a loop device - * The value of the BackingFile property, e.g. /path/to/file.iso - * 42.0 MB Loop Device - * drive-removable-media - * %NULL - * %NULL - * - * - * #UDisksMDRaid - * The value of the Name property, e.g. MirrorOnTheWall - * 12 TB RAID Array - * gdu-enclosure (TODO: use name from icon naming spec) - * %NULL - * %NULL - * - * - * #UDisksBlock whole disk with associated #UDisksMDRaid - * (same as RAID) - * (same as RAID) - * (same as RAID) - * (same as RAID) - * (same as RAID) - * - * - * #UDisksBlock partition with associated #UDisksMDRaid - * (same as RAID) - * Partition N of (RAID description) - * (same as RAID) - * (same as RAID) - * (same as RAID) - * - * - * - * - * * Returns: A #UDisksObjectInfo instance that should be freed with udisks_object_info_unref(). */ UDisksObjectInfo * @@ -3050,7 +2878,7 @@ udisks_client_get_object_info (UDisksClient *client, g_return_val_if_fail (UDISKS_IS_CLIENT (client), NULL); g_return_val_if_fail (UDISKS_IS_OBJECT (object), NULL); - ret = udisks_object_info_new (); + ret = udisks_object_info_new (object); drive = udisks_object_get_drive (object); block = udisks_object_get_block (object); loop = udisks_object_get_loop (object); @@ -3154,7 +2982,7 @@ udisks_client_get_drive_info (UDisksClient *client, g_return_if_fail (UDISKS_IS_CLIENT (client)); g_return_if_fail (UDISKS_IS_DRIVE (drive)); - info = udisks_object_info_new (); + info = udisks_object_info_new (NULL); udisks_client_get_object_info_for_drive (client, drive, info); if (out_name != NULL) diff --git a/udisks/udisksclient.h b/udisks/udisksclient.h index 104eb26..9fc089a 100644 --- a/udisks/udisksclient.h +++ b/udisks/udisksclient.h @@ -153,7 +153,8 @@ gchar *udisks_client_get_job_description (UDisksClient *client, * @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 with it being considered an ABI break. + * This struct may grow in the future without it being considered an + * ABI break. */ struct _UDisksPartitionTypeInfo { @@ -169,6 +170,7 @@ void udisks_partition_type_info_free (UDisksPartitionTypeI /** * UDisksObjectInfo: + * @object: The #UDisksObject that the information is for. * @name: (allow-none): An name for the object or %NULL. * @description: (allow-none): A description for the object or %NULL. * @icon: (allow-none): An icon for the object or %NULL. @@ -177,17 +179,32 @@ void udisks_partition_type_info_free (UDisksPartitionTypeI * @media_icon: (allow-none): An icon for the media for the object or %NULL. * @media_icon_symbolic: (allow-none): A symbolic icon for the media for the object or %NULL. * - * Detailed information about a #UDisksObject that is suitable to - * display in an user interface. Use udisks_client_get_object_info() - * to get an instance and udisks_object_info_unref() to free it. + * Detailed information about the D-Bus interfaces (such as + * #UDisksBlock and #UDisksDrive) on a #UDisksObject that is suitable + * to display in an user interface. Use + * udisks_client_get_object_info() to get an instance and + * udisks_object_info_unref() to free it. * - * This struct may grow in the future with it being considered an ABI break. + * The + * HintName + * and/or + * HintIconName + * propreties on associated #UDisksBlock interfaces (if any) may influence + * the @icon and @media_icon fields. + * + * The @media_description, @media_icon and @media_icon_symbolic fields + * are only set for #UDisksDrive interfaces where the drive has + * removable media. + * + * This struct may grow in the future without it being considered an + * ABI break. */ struct _UDisksObjectInfo { /*< private >*/ volatile gint ref_count; /*< public >*/ + UDisksObject *object; gchar *name; gchar *description; GIcon *icon; -- 2.7.4