GsUtils

GsUtils — Utilities that plugins can use

Stability Level

Unstable, unless otherwise indicated

Functions

Types and Values

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 .

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 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_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_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_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


gs_utils_set_online_updates_timestamp ()

void
gs_utils_set_online_updates_timestamp (GSettings *settings);

Sets the value of online-updates-timestamp to current epoch. "online-updates-timestamp" represents the last time the system was online and got any updates.

It also sets the "update-notification-timestamp", to not receive notifications about available updates too early after the actual update happened.


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

GsMainContextPusher *
gs_main_context_pusher_new (GMainContext *main_context);

gs_main_context_pusher_free ()

void
gs_main_context_pusher_free (GsMainContextPusher *pusher);

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

 

GS_UTILS_CACHE_FLAG_CREATE_DIRECTORY

Create the cache directory (Since: 40)

 

GS_UTILS_CACHE_FLAG_LAST

   

GsMainContextPusher

typedef void GsMainContextPusher;