HAL Support Functions

HAL Support Functions — Miscellaneous Utility Functions for HAL integration

Synopsis


#include <exo-hal/exo-hal.h>

gboolean            exo_hal_init                        (void);
gboolean            exo_hal_udi_validate                (const gchar *udi,
                                                         gssize len,
                                                         gchar **end);
gchar *             exo_hal_drive_compute_display_name  (struct LibHalContext_s *context,
                                                         struct LibHalDrive_s *drive);
GList *             exo_hal_drive_compute_icon_list     (struct LibHalContext_s *context,
                                                         struct LibHalDrive_s *drive);
gchar *             exo_hal_volume_compute_display_name (struct LibHalContext_s *context,
                                                         struct LibHalVolume_s *volume,
                                                         struct LibHalDrive_s *drive);
GList *             exo_hal_volume_compute_icon_list    (struct LibHalContext_s *context,
                                                         struct LibHalVolume_s *volume,
                                                         struct LibHalDrive_s *drive);

Description

This is an additional library that ships with the exo package and offers support functions for HAL integration, that are used by exo-mount and Thunar to figure out display names and icons to visually present HAL devices to the user. The library may also be used by other components to offer smooth integration between various parts of the desktop, making sure that the same names and icons are used for devices everywhere.

Since HAL is currently an optional dependency for Xfce, you should first check whether HAL support is really available by calling the exo_hal_init() function, which returns TRUE if HAL support is available and the other functions will be able to do their work, or FALSE if the functions will return hardcoded default values instead. The exo_hal_init() also takes care of setting up the internationalization support, so make sure you call it first.

The HAL support module is not part of the main exo library, so you if you want to use any of these functions you will need to explicitly link to the exo-hal library. This is done with the pkg-config utility, using exo-hal-0.3 as the package name.

Details

exo_hal_init ()

gboolean            exo_hal_init                        (void);

Initializes the HAL support module, which includes setting up the internationalization support. Returns TRUE if support for HAL was enabled at compile time, FALSE otherwise.

Make sure you call this function first prior to calling any of the functions below.

Returns :

TRUE if HAL support is available, FALSE otherwise.

Since 0.3.1.13


exo_hal_udi_validate ()

gboolean            exo_hal_udi_validate                (const gchar *udi,
                                                         gssize len,
                                                         gchar **end);

Checks that the given range of the udi is a valid HAL device UDI (i.e. a valid D-BUS object path name in the D-BUS protocol). Part of the validation ensures that the udi contains only ASCII.

If end is non-NULL, then then end of the valid range will be stored there (i.e. the start of the first invalid character if some bytes were invalid, or the end of the text being validated otherwise).

Returns TRUE if all of udi was valid. All HAL routines require valid UDIs as input; so data read from a file or the command line should be checked with exo_hal_udi_validate() before doing anything else with it.

Note that exo_hal_udi_validate() is always available, no matter if HAL support was enabled at compile time.

udi :

the HAL device UDI.

len :

the max number of bytes to validate, or -1 to go until NUL.

end :

return location for end of valid data.

Returns :

TRUE if udi was a valid HAL device UDI.

Since 0.3.1.13


exo_hal_drive_compute_display_name ()

gchar *             exo_hal_drive_compute_display_name  (struct LibHalContext_s *context,
                                                         struct LibHalDrive_s *drive);

Computes a usable display name that should be used to present drive to the user. May return NULL if it's unable to determine a display name (i.e. if HAL support is not available), in which case the caller should try to come up with a fallback name on it's own (i.e. using the basename of the drives device file or something like that).

The caller is responsible to free the returned string using g_free() when no longer needed.

context :

a LibHalContext, connected to the HAL daemon.

drive :

a LibHalDrive.

Returns :

a display name for the drive that should be used to present the drive to the user or NULL if the function is unable to come up with a usable name and the caller should figure out a fallback name on its own.

Since 0.3.1.13


exo_hal_drive_compute_icon_list ()

GList *             exo_hal_drive_compute_icon_list     (struct LibHalContext_s *context,
                                                         struct LibHalDrive_s *drive);

Tries to find a list of icon names that may be used to visually present drive to the user. The list is sorted by relevance, with the best icon matches appearing first in the list.

The caller is responsible to free the returned list using

g_list_foreach (list, (GFunc) g_free, NULL);
g_list_free (list);

when no longer needed.

context :

a LibHalContext, connected to the HAL daemon.

drive :

a LibHalDrive.

Returns :

a list of icon names for icons that can be used to visually represent the drive to the user.

Since 0.3.1.13


exo_hal_volume_compute_display_name ()

gchar *             exo_hal_volume_compute_display_name (struct LibHalContext_s *context,
                                                         struct LibHalVolume_s *volume,
                                                         struct LibHalDrive_s *drive);

Similar to exo_hal_drive_compute_display_name(), but tries to find a suitable display name for the volume first, falling back to drive under certain conditions. This function may return NULL if no suitable display name was found.

The caller is responsible to free the returned string using g_free() when no longer needed.

context :

a LibHalContext, connected to the HAL daemon.

volume :

a LibHalVolume.

drive :

the LibHalDrive of the volume.

Returns :

the display name for the volume or NULL if the function is unable to determine the display name.

Since 0.3.1.13


exo_hal_volume_compute_icon_list ()

GList *             exo_hal_volume_compute_icon_list    (struct LibHalContext_s *context,
                                                         struct LibHalVolume_s *volume,
                                                         struct LibHalDrive_s *drive);

Similar to exo_hal_drive_compute_icon_name(), but first looks for icons for volume, falling back to an icons for drive.

The caller is responsible to free the returned list using

g_list_foreach (list, (GFunc) g_free, NULL);
g_list_free (list);

when no longer needed.

context :

a LibHalContext, connected to the HAL daemon.

volume :

a LibHalVolume.

drive :

the LibHalDrive of the volume.

Returns :

a list of icon names for icons that can be used to visually represent the volume to the user.

Since 0.3.1.13

See Also

HAL Specification