GsUtils: GNOME Software Reference Manual

## GsUtils GsUtils — Utilities that plugins can use |

## Stability Level

Unstable, unless otherwise indicated

## Functions

guint | gs_utils_get_file_age ()
gchar * | gs_utils_get_content_type ()
gboolean | gs_utils_symlink ()
gboolean | gs_utils_unlink ()
gboolean | gs_mkdir_parent ()
gchar * | gs_utils_get_cache_filename ()
gchar * | gs_utils_get_user_hash ()
GPermission * | gs_utils_get_permission ()
gboolean | gs_utils_strv_fnmatch ()
GDesktopAppInfo * | gs_utils_get_desktop_app_info ()
gboolean | gs_utils_rmtree ()
gint | gs_utils_get_wilson_rating ()
void | gs_utils_error_add_unique_id ()
void | gs_utils_error_strip_unique_id ()
gboolean | gs_utils_error_convert_gio ()
gboolean | gs_utils_error_convert_gresolver ()
gboolean | gs_utils_error_convert_gdbus ()
gboolean | gs_utils_error_convert_gdk_pixbuf ()
gboolean | gs_utils_error_convert_json_glib ()
gboolean | gs_utils_error_convert_appstream ()
gboolean | gs_utils_is_low_resolution ()
gchar * | gs_utils_get_url_scheme ()
gchar * | gs_utils_get_url_path ()
const gchar * | gs_user_agent ()
void | gs_utils_append_key_value ()
guint | gs_utils_get_memory_total ()
gboolean | gs_utils_parse_evr ()

## Types and Values

enum | GsUtilsCacheFlags

## Includes

    #include <gnome-software.h>

## Description

These functions provide useful functionality that makes it easy to add new plugin functions.

## Functions

### gs_utils_get_file_age ()

    guint
    gs_utils_get_file_age (GFile *file);

Gets a file age.

#### Parameters

file | A GFile |

#### Returns

The time in seconds since the file was modified, or `G_MAXUINT` for error

### gs_utils_get_content_type ()

    gchar *
    gs_utils_get_content_type (GFile *file,
                               GCancellable *cancellable,
                               GError **error);

Gets the standard content type for a file.

#### Parameters

file | A GFile |
cancellable | A GCancellable, or `NULL` |
error | A GError, or `NULL` |

#### Returns

the content type, or `NULL`, e.g. "text/plain"

### gs_utils_symlink ()

    gboolean
    gs_utils_symlink (const gchar *target,
                      const gchar *linkpath,
                      GError **error);

Creates a symlink that can cross filesystem boundaries. Any parent directories needed for target to exist are also created.

#### Parameters

target | the full path of the symlink to create |
linkpath | where the symlink should point to |
error | A GError, or `NULL` |

#### Returns

`TRUE` for success

### gs_utils_unlink ()

    gboolean
    gs_utils_unlink (const gchar *filename,
                     GError **error);

Deletes a file from disk.

#### Parameters

filename | A full pathname to delete |
error | A GError, or `NULL` |

#### Returns

`TRUE` for success

### gs_mkdir_parent ()

    gboolean
    gs_mkdir_parent (const gchar *path,
                     GError **error);

Creates any required directories, including any parent directories.

#### Parameters

path | A full pathname |
error | A GError, or `NULL` |

#### Returns

`TRUE` for success

### gs_utils_get_cache_filename ()

    gchar *
    gs_utils_get_cache_filename (const gchar *kind,
                                 const gchar *resource,
                                 GsUtilsCacheFlags flags,
                                 GError **error);

Returns a filename that points into the cache. This may be per-system or per-user, the latter being more likely when `GS_UTILS_CACHE_FLAG_WRITEABLE` is specified in `flags` .

If `GS_UTILS_CACHE_FLAG_USE_HASH` is set in `flags` then the returned filename will contain the hashed version of `resource` .

If there is more than one match, the file that has been modified last is returned.

If a plugin requests a file to be saved in the cache it is the plugins responsibility to remove the file when it is no longer valid or is too old -- gnome-software will not ever clean the cache for the plugin. For this reason it is a good idea to use the plugin name as `kind` .

#### Parameters

kind | A cache kind, e.g. "fwupd" or "screenshots/123x456" |
resource | A resource, e.g. "system.bin" or "http://foo.bar/baz.bin" |
flags | Some GsUtilsCacheFlags, e.g. `GS_UTILS_CACHE_FLAG_WRITEABLE` |
error | A GError, or `NULL` |

#### Returns

The full path and filename, which may or may not exist, or `NULL`

### gs_utils_get_user_hash ()

    gchar *
    gs_utils_get_user_hash (GError **error);

This SHA1 hash is composed of the contents of machine-id and your username and is also salted with a hardcoded value.

This provides an identifier that can be used to identify a specific user on a machine, allowing them to cast only one vote or perform one review on each application.

There is no known way to calculate the machine ID or username from the machine hash and there should be no privacy issue.

#### Parameters

error | A GError, or `NULL` |

#### Returns

The user hash, or `NULL` on error

### gs_utils_get_permission ()

    GPermission *
    gs_utils_get_permission (const gchar *id,
                             GCancellable *cancellable,
                             GError **error);

Gets a permission object for an ID.

#### Parameters

id | A PolicyKit ID, e.g. "org.gnome.Desktop" |
cancellable | A GCancellable, or `NULL` |
error | A GError, or `NULL` |

#### Returns

a GPermission, or `NULL` if this if not possible.

### gs_utils_strv_fnmatch ()

    gboolean
    gs_utils_strv_fnmatch (gchar **strv,
                           const gchar *str);

Matches a string against a list of globs.

#### Parameters

strv | A NUL-terminated list of strings |
str | A string |

#### Returns

`TRUE` if the list matches

### gs_utils_get_desktop_app_info ()

    GDesktopAppInfo *
    gs_utils_get_desktop_app_info (const gchar *id);

Gets a a GDesktopAppInfo taking into account the kde4- prefix. If the given `id` doesn not have a ".desktop" suffix, it will add one to it for convenience.

#### Parameters

id | A desktop ID, e.g. "gimp.desktop" |

#### Returns

a GDesktopAppInfo for a specific ID, or `NULL`

### gs_utils_rmtree ()

    gboolean
    gs_utils_rmtree (const gchar *directory,
                     GError **error);

Deletes a directory from disk and all its contents.

#### Parameters

directory | A full directory pathname to delete |
error | A GError, or `NULL` |

#### Returns

`TRUE` for success

### gs_utils_get_wilson_rating ()

    gint
    gs_utils_get_wilson_rating (guint64 star1,
                                guint64 star2,
                                guint64 star3,
                                guint64 star4,
                                guint64 star5);

Returns the lower bound of Wilson score confidence interval for a Bernoulli parameter. This ensures small numbers of ratings don't give overly high scores. See https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval for details.

#### Parameters

star1 | The number of 1 star reviews |
star2 | The number of 2 star reviews |
star3 | The number of 3 star reviews |
star4 | The number of 4 star reviews |
star5 | The number of 5 star reviews |

#### Returns

Wilson rating percentage, or -1 for error

### gs_utils_error_add_unique_id ()

    void
    gs_utils_error_add_unique_id (GError **error,
                                  GsApp *app);

Adds a unique ID prefix to the error.

#### Parameters

error | a GError |
app | a GsApp |

Since: 3.22

### gs_utils_error_strip_unique_id ()

    void
    gs_utils_error_strip_unique_id (GError *error);

Removes a possible unique ID prefix from the error.

#### Parameters

error | a GError |

Since: 3.22

### gs_utils_error_convert_gio ()

    gboolean
    gs_utils_error_convert_gio (GError **perror);

Converts the GIOError to an error with a GsPluginError domain.

#### Parameters

perror | a pointer to a GError, or `NULL` |

#### Returns

`TRUE` if the error was converted, or already correct

### gs_utils_error_convert_gresolver ()

    gboolean
    gs_utils_error_convert_gresolver (GError **perror);

Converts the GResolverError to an error with a GsPluginError domain.

#### Parameters

perror | a pointer to a GError, or `NULL` |

#### Returns

`TRUE` if the error was converted, or already correct

### gs_utils_error_convert_gdbus ()

    gboolean
    gs_utils_error_convert_gdbus (GError **perror);

Converts the GDBusError to an error with a GsPluginError domain.

#### Parameters

perror | a pointer to a GError, or `NULL` |

#### Returns

`TRUE` if the error was converted, or already correct

### gs_utils_error_convert_gdk_pixbuf ()

    gboolean
    gs_utils_error_convert_gdk_pixbuf (GError **perror);

Converts the GdkPixbufError to an error with a GsPluginError domain.

#### Parameters

perror | a pointer to a GError, or `NULL` |

#### Returns

`TRUE` if the error was converted, or already correct

### gs_utils_error_convert_json_glib ()

    gboolean
    gs_utils_error_convert_json_glib (GError **perror);

Converts the JsonParserError to an error with a GsPluginError domain.

#### Parameters

perror | a pointer to a GError, or `NULL` |

#### Returns

`TRUE` if the error was converted, or already correct

### gs_utils_error_convert_appstream ()

    gboolean
    gs_utils_error_convert_appstream (GError **perror);

Converts the various AppStream error types to an error with a GsPluginError domain.

#### Parameters

perror | a pointer to a GError, or `NULL` |

#### Returns

`TRUE` if the error was converted, or already correct

### gs_utils_is_low_resolution ()

    gboolean
    gs_utils_is_low_resolution (GtkWidget *toplevel);

Retrieves whether the primary monitor has a low resolution.

#### Parameters

toplevel | widget on monitor to check |

#### Returns

`TRUE` if the monitor has low resolution

### gs_utils_get_url_scheme ()

    gchar *
    gs_utils_get_url_scheme (const gchar *url);

Gets the scheme from the URL string.

#### Parameters

url | A URL, e.g. "appstream://gimp.desktop" |

#### Returns

the URL scheme, e.g. "appstream"

### gs_utils_get_url_path ()

    gchar *
    gs_utils_get_url_path (const gchar *url);

Gets the path from the URL string, removing any leading slashes.

#### Parameters

url | A URL, e.g. "appstream://gimp.desktop" |

#### Returns

the URL path, e.g. "gimp.desktop"

### gs_user_agent ()

    const gchar *
    gs_user_agent (void);

Gets the user agent to use for remote requests.

#### Returns

the user-agent, e.g. "gnome-software/3.22.1"

### gs_utils_append_key_value ()

    void
    gs_utils_append_key_value (GString *str,
                               gsize align_len,
                               const gchar *key,
                               const gchar *value);

Adds a line to an existing string, padding the key to a set number of spaces.

#### Parameters

str | A GString |
align_len | The alignment of the `value` compared to the `key` |
key | The text to use as a title |
value | The text to use as a value |

Since: 3.26

### gs_utils_get_memory_total ()

    guint
    gs_utils_get_memory_total (void);

### gs_utils_parse_evr ()

    gboolean
    gs_utils_parse_evr (const gchar *evr,
                        gchar **out_epoch,
                        gchar **out_version,
                        gchar **out_release);

Splits EVR into epoch-version-release strings.

#### Parameters

evr | an EVR version string |
out_epoch | return location for the epoch string. | [out]
out_version | return location for the version string. | [out]
out_release | return location for the release string. | [out]

#### Returns

`TRUE` for success

## Types and Values

### enum GsUtilsCacheFlags

The cache flags.

#### Members

GS_UTILS_CACHE_FLAG_NONE | No flags set |
GS_UTILS_CACHE_FLAG_WRITEABLE | A writable directory is required |
GS_UTILS_CACHE_FLAG_USE_HASH | Prefix a hash to the filename |
GS_UTILS_CACHE_FLAG_ENSURE_EMPTY | Clear existing cached items |