GsUtils: GNOME Software Reference Manual

## GsUtils GsUtils — Utilities that plugins can use |

## Stability Level

Unstable, unless otherwise indicated

## Functions

guint64 | gs_utils_get_file_age ()
gchar * | gs_utils_get_content_type ()
void | gs_utils_get_content_type_async ()
gchar * | gs_utils_get_content_type_finish ()
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 ()
void | gs_utils_get_permission_async ()
GPermission * | gs_utils_get_permission_finish ()
gboolean | gs_utils_strv_fnmatch ()
gchar * | gs_utils_sort_key ()
gint | gs_utils_sort_strcmp ()
GDesktopAppInfo * | gs_utils_get_desktop_app_info ()
gboolean | gs_utils_rmtree ()
gint | gs_utils_get_wilson_rating ()
void | gs_utils_error_add_app_id ()
void | gs_utils_error_add_origin_id ()
gchar * | gs_utils_error_strip_app_id ()
gchar * | gs_utils_error_strip_origin_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_appstream ()
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 ()
gchar * | gs_utils_unique_id_compat_convert ()
gchar * | gs_utils_build_unique_id ()
void | gs_utils_pixbuf_blur ()
gboolean | (*GsFileSizeIncludeFunc) ()
guint64 | gs_utils_get_file_size ()
gchar * | gs_utils_get_file_etag ()
gboolean | gs_utils_set_file_etag ()
gchar * | gs_utils_get_upgrade_background ()
gint | gs_utils_app_sort_name ()
gint | gs_utils_app_sort_match_value ()
gint | gs_utils_app_sort_priority ()
void | gs_utils_gstring_replace ()
gint | gs_utils_app_sort_kind ()
gint | gs_utils_compare_versions ()

## 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 ()

    guint64
    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_MAXUINT64` 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_get_content_type_async ()

    void
    gs_utils_get_content_type_async (GFile *file,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Asynchronously get the standard content type for the `file` . Finish the operation with `gs_utils_get_content_type_finish` .

#### Parameters

file | a GFile |
cancellable | a GCancellable, or `NULL` |
callback | callback for when the asynchronous operation is complete |
user_data | data to pass to `callback` |

Since: 47

### gs_utils_get_content_type_finish ()

    gchar *
    gs_utils_get_content_type_finish (GFile *file,
                                      GAsyncResult *result,
                                      GError **error);

Finish an asynchronous operation started with `gs_utils_get_content_type_async()`.

#### Parameters

file | a GFile |
result | result of the asynchronous operation |
error | return location for a GError, or `NULL` |

#### Returns

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

Since: 47

### 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` .

This function can only fail if `GS_UTILS_CACHE_FLAG_ENSURE_EMPTY` or `GS_UTILS_CACHE_FLAG_CREATE_DIRECTORY` are passed in `flags` .

#### 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 app.

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_get_permission_async ()

    void
    gs_utils_get_permission_async (const gchar *id,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Asynchronously gets a GPermission object representing the given polkit action `id` .

#### Parameters

id | a polkit action ID, for example `org.freedesktop.packagekit.trigger-offline-update` |
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | callback for when the asynchronous operation is complete |
user_data | data to pass to `callback` |

Since: 42

### gs_utils_get_permission_finish ()

    GPermission *
    gs_utils_get_permission_finish (GAsyncResult *result,
                                    GError **error);

Finish an asynchronous operation started with `gs_utils_get_permission_async()`.

#### Parameters

result | result of the asynchronous operation |
error | return location for a GError, or `NULL` |

#### Returns

a GPermission representing the given action ID.

[transfer full]

Since: 42

### 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_sort_key ()

    gchar *
    gs_utils_sort_key (const gchar *str);

Useful to sort strings in a locale-sensitive, presentational way. Case is ignored and utf8 collation is used (e.g. accents are ignored).

#### Parameters

str | A string to convert to a sort key |

#### Returns

a newly allocated string sort key

### gs_utils_sort_strcmp ()

    gint
    gs_utils_sort_strcmp (const gchar *str1,
                          const gchar *str2);

Compares two strings in a locale-sensitive, presentational way. Case is ignored and utf8 collation is used (e.g. accents are ignored). `NULL` is sorted before all non-`NULL` strings, and `NULLs` compare equal.

#### Parameters

str1 | A string to compare. | [nullable]
str2 | A string to compare. | [nullable]

#### Returns

< 0 if str1 is before str2, 0 if equal, > 0 if str1 is after str2

### 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_app_id ()

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

Adds app unique ID prefix to the error.

#### Parameters

error | a GError |
app | a GsApp |

Since: 3.30

### gs_utils_error_add_origin_id ()

    void
    gs_utils_error_add_origin_id (GError **error,
                                  GsApp *origin);

Adds origin unique ID prefix to the error.

#### Parameters

error | a GError |
origin | a GsApp |

Since: 3.30

### gs_utils_error_strip_app_id ()

    gchar *
    gs_utils_error_strip_app_id (GError *error);

Removes a possible app ID prefix from the error, and returns the removed app ID.

#### Parameters

error | a GError |

#### Returns

A newly allocated string with the app ID

Since: 3.30

### gs_utils_error_strip_origin_id ()

    gchar *
    gs_utils_error_strip_origin_id (GError *error);

Removes a possible origin ID prefix from the error, and returns the removed origin ID.

#### Parameters

error | a GError |

#### Returns

A newly allocated string with the origin ID

Since: 3.30

### 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_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_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);

### gs_utils_unique_id_compat_convert ()

    gchar *
    gs_utils_unique_id_compat_convert (const gchar *data_id);

Converts the unique ID string from its legacy 6-part form into a new-style 5-part AppStream data-id. Does nothing if the string is already valid.

See !583 for the history of this conversion.

#### Parameters

data_id | A string that may be a unique component ID. | [nullable]

#### Returns

A newly allocated string with the new-style data-id, or `NULL` if input was no valid ID.

[nullable]

Since: 40

### gs_utils_build_unique_id ()

    gchar *
    gs_utils_build_unique_id (AsComponentScope scope,
                              AsBundleKind bundle_kind,
                              const gchar *origin,
                              const gchar *cid,
                              const gchar *branch);

Builds an identifier string unique to the individual dataset using the supplied information. It's similar to `as_utils_build_data_id()`, except it respects the `origin` for the packages.

#### Parameters

scope | Scope of the metadata as AsComponentScope e.g. `AS_COMPONENT_SCOPE_SYSTEM` |
bundle_kind | Bundling system providing this data, e.g. 'package' or 'flatpak' |
origin | Origin string, e.g. 'os' or 'gnome-apps-nightly' |
cid | AppStream component ID, e.g. 'org.freedesktop.appstream.cli' |
branch | Branch, e.g. '3-20' or 'master' |

#### Returns

a unique ID, free with `g_free()`, when no longer needed.

[transfer full]

Since: 41

### gs_utils_pixbuf_blur ()

    void
    gs_utils_pixbuf_blur (GdkPixbuf *src,
                          guint radius,
                          guint iterations);

Blurs an image. Warning, this method is s..l..o..w... for large images.

#### Parameters

src | the GdkPixbuf. |
radius | the pixel radius for the gaussian blur, typical values are 1..3 |
iterations | Amount to blur the image, typical values are 1..5 |

### GsFileSizeIncludeFunc ()

    gboolean
    (*GsFileSizeIncludeFunc) (const gchar *filename,
                              GFileTest file_kind,
                              gpointer user_data);

Check whether include the `filename` in the size calculation. The `filename` is a relative path to the file name passed to the GsFileSizeIncludeFunc.

#### Parameters

filename | file name to check |
file_kind | the file kind, one of GFileTest enums |
user_data | a user data passed to the `gs_utils_get_file_size()` |

#### Returns

Whether to include the `filename` in the size calculation

Since: 41

### gs_utils_get_file_size ()

    guint64
    gs_utils_get_file_size (const gchar *filename,
                            GsFileSizeIncludeFunc include_func,
                            gpointer user_data,
                            GCancellable *cancellable);

Gets the size of the file or a directory identified by `filename` .

When the `include_func` is not `NULL`, it can limit which files are included in the resulting size. When it's `NULL`, all files and subdirectories are included.

#### Parameters

filename | a file name to get the size of; it can be a file or a directory |
include_func | optional callback to limit what files to count. | [nullable][scope call]
user_data | user data passed to the `include_func` |
cancellable | an optional GCancellable or `NULL`. | [nullable]

#### Returns

disk size of the `filename` ; or 0 when not found

Since: 41

### gs_utils_get_file_etag ()

    gchar *
    gs_utils_get_file_etag (GFile *file,
                            GDateTime **last_modified_date_out,
                            GCancellable *cancellable);

Gets the ETag for the `file` , previously stored by `gs_utils_set_file_etag()`.

#### Parameters

file | a file to get the ETag for |
last_modified_date_out | return location for the last modified date of the file (`NULL` to ignore), or `NULL` if unknown. | [out callee-allocates][transfer full][optional][nullable]
cancellable | an optional GCancellable or `NULL`. | [nullable]

#### Returns

The ETag stored for the `file` , or `NULL`, when the file does not exist, no ETag is stored for it or other error occurs.

[nullable][transfer full]

Since: 43

### gs_utils_set_file_etag ()

    gboolean
    gs_utils_set_file_etag (GFile *file,
                            const gchar *etag,
                            GCancellable *cancellable);

Sets the ETag for the `file` . When the `etag` is `NULL` or an empty string, then unsets the ETag for the `file` . The ETag can be read back with `gs_utils_get_file_etag()`.

The `file` should exist, otherwise the function fails.

#### Parameters

file | a file to get the ETag for |
etag | an ETag to set. | [nullable]
cancellable | an optional GCancellable or `NULL`. | [nullable]

#### Returns

whether succeeded.

Since: 42

### gs_utils_get_upgrade_background ()

    gchar *
    gs_utils_get_upgrade_background (const gchar *version);

Get the path to a background image to display as the background for a banner advertising an upgrade to the given `version` .

If a path is returned, it’s guaranteed to exist on the file system.

Vendors can drop their customised backgrounds in this directory for them to be used by gnome-software. See `doc/vendor-customisation.md`.

#### Parameters

version | version string of the upgrade (which must be non-empty if provided), or `NULL` if unknown. | [nullable]

#### Returns

path to an upgrade background image to use, or `NULL` if a suitable one didn’t exist.

[transfer full][type filename][nullable]

Since: 42

### gs_utils_app_sort_name ()

    gint
    gs_utils_app_sort_name (GsApp *app1,
                            GsApp *app2,
                            gpointer user_data);

Comparison function to sort apps in increasing alphabetical order of name.

This is suitable for passing to `gs_app_list_sort()`.

#### Parameters

app1 | a GsApp |
app2 | another GsApp |
user_data | data passed to the sort function |

#### Returns

a `strcmp()`-style sort value comparing `app1` to `app2`

Since: 43

### gs_utils_app_sort_match_value ()

    gint
    gs_utils_app_sort_match_value (GsApp *app1,
                                   GsApp *app2,
                                   gpointer user_data);

Comparison function to sort apps in decreasing order of match value (“match-value”).

This is suitable for passing to `gs_app_list_sort()`.

#### Parameters

app1 | a GsApp |
app2 | another GsApp |
user_data | data passed to the sort function |

#### Returns

a `strcmp()`-style sort value comparing `app1` to `app2`

Since: 43

### gs_utils_app_sort_priority ()

    gint
    gs_utils_app_sort_priority (GsApp *app1,
                                GsApp *app2,
                                gpointer user_data);

Comparison function to sort apps in increasing order of their priority (“priority”).

This is suitable for passing to `gs_app_list_sort()`.

#### Parameters

app1 | a GsApp |
app2 | another GsApp |
user_data | data passed to the sort function |

#### Returns

a `strcmp()`-style sort value comparing `app1` to `app2`

Since: 43

### gs_utils_gstring_replace ()

    void
    gs_utils_gstring_replace (GString *str,
                              const gchar *find,
                              const gchar *replace);

Replaces all `find` occurrences in `str` with `replace` .

#### Parameters

str | a GString to replace the text in |
find | a text to find |
replace | a text to replace the found text with |

Since: 45

### gs_utils_app_sort_kind ()

    gint
    gs_utils_app_sort_kind (GsApp *app1,
                            GsApp *app2);

Comparison function to sort apps by Appstream kind, then by increasing alphabetical order of name.

This is useful for sorting apps with multiple kinds (E.g Updates / Updated pages), as opposed to category pages where all apps are of the same kind.

#### Parameters

app1 | a GsApp |
app2 | another GsApp |

#### Returns

< 0 if app1 is before app2, 0 if equal, > 0 if app1 is after app2

Since: 47

### gs_utils_compare_versions ()

    gint
    gs_utils_compare_versions (const gchar *ver1,
                               const gchar *ver2);

Compares `ver1` and `ver2` , return value as ``strcmp()``, that is, a number below zero, when the `ver1` is before `ver2` zero, when `ver1` is the same as `ver2` , and a number above zero, when `ver1` is lower than `ver2` .

#### Parameters

ver1 | the first version string |
ver2 | the second version string |

#### Returns

a compare result of the two version string comparison

Since: 48

## 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 all existing cached items in the cache kind (not just the specified resource) |
GS_UTILS_CACHE_FLAG_CREATE_DIRECTORY | Create the cache directory (Since: 40) |
GS_UTILS_CACHE_FLAG_LAST |  |