Utilities

## Utilities Utilities — Various utility routines |

## Synopsis

    gchar *             udisks_decode_udev_string           (const gchar *str);
    void                udisks_safe_append_to_object_path   (GString *str,
                                                             const gchar *s);
    guint64             udisks_daemon_util_block_get_size   (GUdevDevice *device,
                                                             gboolean *out_media_available,
                                                             gboolean *out_media_change_detected);
    gchar *             udisks_daemon_util_resolve_link     (const gchar *path,
                                                             const gchar *name);
    gchar **            udisks_daemon_util_resolve_links    (const gchar *path,
                                                             const gchar *dir_name);
    gboolean            udisks_daemon_util_check_authorization_sync
                                                            (UDisksDaemon *daemon,
                                                             UDisksObject *object,
                                                             const gchar *action_id,
                                                             GVariant *options,
                                                             const gchar *message,
                                                             GDBusMethodInvocation *invocation);
    gboolean            udisks_daemon_util_get_caller_uid_sync
                                                            (UDisksDaemon *daemon,
                                                             GDBusMethodInvocation *invocation,
                                                             GCancellable *cancellable,
                                                             uid_t *out_uid,
                                                             gid_t *out_gid,
                                                             gchar **out_user_name,
                                                             GError **error);
    gboolean            udisks_daemon_util_get_caller_pid_sync
                                                            (UDisksDaemon *daemon,
                                                             GDBusMethodInvocation *invocation,
                                                             GCancellable *cancellable,
                                                             pid_t *out_pid,
                                                             GError **error);
    gboolean            udisks_daemon_util_setup_by_user    (UDisksDaemon *daemon,
                                                             UDisksObject *object,
                                                             uid_t user);
    gpointer            udisks_daemon_util_dup_object       (gpointer interface_,
                                                             GError **error);
    gchar *             udisks_daemon_util_escape           (const gchar *str);
    gchar *             udisks_daemon_util_escape_and_quote (const gchar *str);

## Description

Various utility routines.

## Details

### udisks_decode_udev_string ()

    gchar *             udisks_decode_udev_string           (const gchar *str);

Unescapes sequences like \x20 to " " and ensures the returned string is valid UTF-8.

If the string is not valid UTF-8, try as hard as possible to convert to UTF-8.

If `NULL` is passed, then `NULL` is returned.

See `udev_util_encode_string()` in libudev/libudev-util.c in the udev tree for what kinds of strings can be used.

`str` : | An udev-encoded string or `NULL`.
Returns : | A valid UTF-8 string that must be freed with `g_free()`.

### udisks_safe_append_to_object_path ()

    void                udisks_safe_append_to_object_path   (GString *str,
                                                             const gchar *s);

Appends `s` to `str` in a way such that only characters that can be used in a D-Bus object path will be used. E.g. a character not in `[A-Z][a-z][0-9]_` will be escaped as _HEX where HEX is a two-digit hexadecimal number.

Note that his mapping is not bijective - e.g. you cannot go back to the original string.

`str` : | A GString to append to.
`s` : | A UTF-8 string.

### udisks_daemon_util_block_get_size ()

    guint64             udisks_daemon_util_block_get_size   (GUdevDevice *device,
                                                             gboolean *out_media_available,
                                                             gboolean *out_media_change_detected);

Gets the size of the `device` top-level block device, checking for media in the process

`device` : | A GUdevDevice for a top-level block device.
`out_media_available` : | Return location for whether media is available or `NULL`. [out]
`out_media_change_detected` : | Return location for whether media change is detected or `NULL`. [out]
Returns : | The size of `device` or 0 if no media is available or if unknown.

### udisks_daemon_util_resolve_link ()

    gchar *             udisks_daemon_util_resolve_link     (const gchar *path,
                                                             const gchar *name);

Resolves the symlink `path`/`name`.

`path` : | A path
`name` : | Name of a symlink in `path`.
Returns : | A canonicalized absolute pathname or `NULL` if the symlink could not be resolved. Free with `g_free()`.

### udisks_daemon_util_resolve_links ()

    gchar **            udisks_daemon_util_resolve_links    (const gchar *path,
                                                             const gchar *dir_name);

Resolves all symlinks in `path`/`dir_name`. This can be used to easily walk e.g. holders or slaves of block devices.

`path` : | A path
`dir_name` : | Name of a directory in `path` holding symlinks.
Returns : | An array of canonicalized absolute pathnames. Free with `g_strfreev()`.

### udisks_daemon_util_check_authorization_sync ()

    gboolean            udisks_daemon_util_check_authorization_sync
                                                            (UDisksDaemon *daemon,
                                                             UDisksObject *object,
                                                             const gchar *action_id,
                                                             GVariant *options,
                                                             const gchar *message,
                                                             GDBusMethodInvocation *invocation);

Checks if the caller represented by `invocation` is authorized for the action identified by `action_id`, optionally displaying `message` if authentication is needed. Additionally, if the caller is not authorized, the appropriate error is already returned to the caller via `invocation`.

The calling thread is blocked for the duration of the authorization check which could be a very long time since it may involve presenting an authentication dialog and having a human user use it. If “auth.no_user_interaction” in `options` is `TRUE` no authentication dialog will be presented and the check is not expected to take a long time.

See Table 1, “Known polkit variables” for the variables that can be used in `message` but note that not all variables can be used in all checks. For example, any check involving a UDisksDrive or a UDisksBlock object can safely include the fragment “$(drive)” since it will always expand to the name of the drive, e.g. “INTEL SSDSA2MH080G1GC (/dev/sda1)” or the block device file e.g. “/dev/vg_lucifer/lv_root” or “/dev/sda1”. However this won't work for operations that isn't on a drive or block device, for example calls on the Manager object.

`daemon` : | A UDisksDaemon.
`object` : | The GDBusObject that the call is on or `NULL`. [allow-none]
`action_id` : | The action id to check for.
`options` : | A GVariant to check for the “auth.no_user_interaction” option or `NULL`. [allow-none]
`message` : | The message to convey (use N_).
`invocation` : | The invocation to check for.
Returns : | `TRUE` if caller is authorized, `FALSE` if not.

### udisks_daemon_util_get_caller_uid_sync ()

    gboolean            udisks_daemon_util_get_caller_uid_sync
                                                            (UDisksDaemon *daemon,
                                                             GDBusMethodInvocation *invocation,
                                                             GCancellable *cancellable,
                                                             uid_t *out_uid,
                                                             gid_t *out_gid,
                                                             gchar **out_user_name,
                                                             GError **error);

Gets the UNIX user id (and possibly group id and user name) of the peer represented by `invocation`.

`daemon` : | A UDisksDaemon.
`invocation` : | A GDBusMethodInvocation.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`out_uid` : | Return location for resolved uid or `NULL`. [out]
`out_gid` : | Return location for resolved gid or `NULL`. [out][allow-none]
`out_user_name` : | Return location for resolved user name or `NULL`. [out][allow-none]
`error` : | Return location for error.
Returns : | `TRUE` if the user id (and possibly group id) was obtained, `FALSE` otherwise

### udisks_daemon_util_get_caller_pid_sync ()

    gboolean            udisks_daemon_util_get_caller_pid_sync
                                                            (UDisksDaemon *daemon,
                                                             GDBusMethodInvocation *invocation,
                                                             GCancellable *cancellable,
                                                             pid_t *out_pid,
                                                             GError **error);

Gets the UNIX process id of the peer represented by `invocation`.

`daemon` : | A UDisksDaemon.
`invocation` : | A GDBusMethodInvocation.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`out_pid` : | Return location for resolved pid or `NULL`. [out]
`error` : | Return location for error.
Returns : | `TRUE` if the process id was obtained, `FALSE` otherwise

### udisks_daemon_util_setup_by_user ()

    gboolean            udisks_daemon_util_setup_by_user    (UDisksDaemon *daemon,
                                                             UDisksObject *object,
                                                             uid_t user);

Checks whether the device represented by `object` (if any) has been setup by `user`.

`daemon` : | A UDisksDaemon.
`object` : | The GDBusObject that the call is on or `NULL`.
`user` : | The user in question.
Returns : | `TRUE` if `object` has been set-up by `user`, `FALSE` if not.

### udisks_daemon_util_dup_object ()

    gpointer            udisks_daemon_util_dup_object       (gpointer interface_,
                                                             GError **error);

Gets the enclosing UDisksObject for `interface`, if any.

`interface_` : | A GDBusInterface-derived instance. [type GDBusInterface]
`error` : | `NULL`, or an unset GError to set if the return value is `NULL`.
Returns : | Either `NULL` or a UDisksObject-derived instance that must be released with `g_object_unref()`. [transfer full][type UDisksObject]

### udisks_daemon_util_escape ()

    gchar *             udisks_daemon_util_escape           (const gchar *str);

Escapes double-quotes (") and back-slashes (\) in a string using back-slash (\).

`str` : | The string to escape.
Returns : | The escaped string. Free with `g_free()`.

### udisks_daemon_util_escape_and_quote ()

    gchar *             udisks_daemon_util_escape_and_quote (const gchar *str);

Like `udisks_daemon_util_escape()` but also wraps the result in double-quotes.

`str` : | The string to escape.
Returns : | The double-quoted and escaped string. Free with `g_free()`.