## 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 `drive`s 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