as-utils

as-utils — Helper functions that are used inside libappstream-glib

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <appstream-glib.h>

enum                AsUtilsError;
#define             AS_UTILS_ERROR
enum                AsUtilsFindIconFlag;
enum                AsUtilsLocation;
enum                AsVersionParseFlag;
enum                AsUniqueIdMatchFlags;
GQuark              as_utils_error_quark                (void);
gboolean            as_utils_is_stock_icon_name         (const gchar *name);
gboolean            as_utils_is_spdx_license_id         (const gchar *license_id);
gboolean            as_utils_is_spdx_license            (const gchar *license);
gboolean            as_utils_is_environment_id          (const gchar *environment_id);
gboolean            as_utils_is_category_id             (const gchar *category_id);
gboolean            as_utils_is_blacklisted_id          (const gchar *desktop_id);
gchar **            as_utils_spdx_license_tokenize      (const gchar *license);
gchar *             as_utils_spdx_license_detokenize    (gchar **license_tokens);
gchar *             as_utils_license_to_spdx            (const gchar *license);
gchar *             as_utils_find_icon_filename         (const gchar *destdir,
                                                         const gchar *search,
                                                         GError **error);
gchar *             as_utils_find_icon_filename_full    (const gchar *destdir,
                                                         const gchar *search,
                                                         AsUtilsFindIconFlag flags,
                                                         GError **error);
gboolean            as_utils_install_filename           (AsUtilsLocation location,
                                                         const gchar *filename,
                                                         const gchar *origin,
                                                         const gchar *destdir,
                                                         GError **error);
gboolean            as_utils_search_token_valid         (const gchar *token);
gchar **            as_utils_search_tokenize            (const gchar *search);
gint                as_utils_vercmp                     (const gchar *version_a,
                                                         const gchar *version_b);
gboolean            as_utils_guid_is_valid              (const gchar *guid);
gchar *             as_utils_guid_from_string           (const gchar *str);
gchar *             as_utils_guid_from_data             (const gchar *namespace_id,
                                                         const guint8 *data,
                                                         gsize data_len,
                                                         GError **error);
gchar *             as_utils_version_from_uint32        (guint32 val,
                                                         AsVersionParseFlag flags);
gchar *             as_utils_version_from_uint16        (guint16 val,
                                                         AsVersionParseFlag flags);
gchar *             as_utils_version_parse              (const gchar *version);
guint               as_utils_string_replace             (GString *string,
                                                         const gchar *search,
                                                         const gchar *replace);
gchar *             as_utils_unique_id_build            (AsAppScope scope,
                                                         AsBundleKind bundle_kind,
                                                         const gchar *origin,
                                                         AsAppKind kind,
                                                         const gchar *id,
                                                         const gchar *branch);
gboolean            as_utils_unique_id_equal            (const gchar *unique_id1,
                                                         const gchar *unique_id2);
gboolean            as_utils_unique_id_match            (const gchar *unique_id1,
                                                         const gchar *unique_id2,
                                                         AsUniqueIdMatchFlags match_flags);
gboolean            as_utils_unique_id_valid            (const gchar *unique_id);
guint               as_utils_unique_id_hash             (const gchar *unique_id);
gchar *             as_utils_appstream_id_build         (const gchar *str);
gboolean            as_utils_appstream_id_valid         (const gchar *str);

Description

These functions are used internally to libappstream-glib, and some may be useful to user-applications.

Details

enum AsUtilsError

typedef enum {
	AS_UTILS_ERROR_FAILED,
	AS_UTILS_ERROR_INVALID_TYPE,
} AsUtilsError;

The error type.

AS_UTILS_ERROR_FAILED

Generic failure

AS_UTILS_ERROR_INVALID_TYPE

Invalid type

AS_UTILS_ERROR

#define AS_UTILS_ERROR				as_utils_error_quark ()

enum AsUtilsFindIconFlag

typedef enum {
	AS_UTILS_FIND_ICON_NONE			= 0,
	AS_UTILS_FIND_ICON_HI_DPI		= 1 << 0,
} AsUtilsFindIconFlag;

The flags used when finding icons.

AS_UTILS_FIND_ICON_NONE

No flags set

AS_UTILS_FIND_ICON_HI_DPI

Prefer a HiDPI icon

enum AsUtilsLocation

typedef enum {
	AS_UTILS_LOCATION_SHARED,
	AS_UTILS_LOCATION_CACHE,
	AS_UTILS_LOCATION_USER,
} AsUtilsLocation;

The flags used when installing and removing metadata files.

AS_UTILS_LOCATION_SHARED

Installed by the vendor, shared

AS_UTILS_LOCATION_CACHE

Installed as metadata, shared

AS_UTILS_LOCATION_USER

Installed by the user

enum AsVersionParseFlag

typedef enum {
	AS_VERSION_PARSE_FLAG_NONE		= 0,
	AS_VERSION_PARSE_FLAG_USE_TRIPLET = 1 << 0,
	AS_VERSION_PARSE_FLAG_USE_BCD		= 1 << 1, /* Since: 0.7.3 */
} AsVersionParseFlag;

The flags used when parsing version numbers.

AS_VERSION_PARSE_FLAG_NONE

No flags set

AS_VERSION_PARSE_FLAG_USE_TRIPLET

Use Microsoft-style version numbers

AS_VERSION_PARSE_FLAG_USE_BCD

Use binary coded decimal notation

enum AsUniqueIdMatchFlags

typedef enum {
	AS_UNIQUE_ID_MATCH_FLAG_NONE		= 0,
	AS_UNIQUE_ID_MATCH_FLAG_SCOPE		= 1 << 0,
	AS_UNIQUE_ID_MATCH_FLAG_BUNDLE_KIND = 1 << 1, /* Since: 0.7.8 */
	AS_UNIQUE_ID_MATCH_FLAG_ORIGIN		= 1 << 2, /* Since: 0.7.8 */
	AS_UNIQUE_ID_MATCH_FLAG_KIND		= 1 << 3, /* Since: 0.7.8 */
	AS_UNIQUE_ID_MATCH_FLAG_ID		= 1 << 4, /* Since: 0.7.8 */
	AS_UNIQUE_ID_MATCH_FLAG_BRANCH		= 1 << 5, /* Since: 0.7.8 */
} AsUniqueIdMatchFlags;

The flags used when matching unique IDs.

AS_UNIQUE_ID_MATCH_FLAG_NONE

No flags set

AS_UNIQUE_ID_MATCH_FLAG_SCOPE

Scope, e.g. a AsAppScope

AS_UNIQUE_ID_MATCH_FLAG_BUNDLE_KIND

Bundle kind, e.g. a AsBundleKind

AS_UNIQUE_ID_MATCH_FLAG_ORIGIN

Origin

AS_UNIQUE_ID_MATCH_FLAG_KIND

Component kind, e.g. a AsAppKind

AS_UNIQUE_ID_MATCH_FLAG_ID

Component AppStream ID

AS_UNIQUE_ID_MATCH_FLAG_BRANCH

Branch

as_utils_error_quark ()

GQuark              as_utils_error_quark                (void);

Returns :

An error quark.

Since 0.3.7


as_utils_is_stock_icon_name ()

gboolean            as_utils_is_stock_icon_name         (const gchar *name);

Searches the known list of stock icons.

name :

an icon name

Returns :

TRUE if the icon is a "stock icon name" and does not need to be included in the AppStream icon tarball

Since 0.1.3


as_utils_is_spdx_license_id ()

gboolean            as_utils_is_spdx_license_id         (const gchar *license_id);

Searches the known list of SPDX license IDs.

license_id :

a single SPDX license ID, e.g. "CC-BY-3.0"

Returns :

TRUE if the license ID is a valid "SPDX license ID"

Since 0.1.5


as_utils_is_spdx_license ()

gboolean            as_utils_is_spdx_license            (const gchar *license);

Checks the licence string to check it being a valid licence. NOTE: SPDX licences can't typically contain brackets.

license :

a SPDX license string, e.g. "CC-BY-3.0 and GFDL-1.3"

Returns :

TRUE if the license is a valid "SPDX license"

Since 0.2.5


as_utils_is_environment_id ()

gboolean            as_utils_is_environment_id          (const gchar *environment_id);

Searches the known list of registered environment IDs.

environment_id :

a desktop ID, e.g. "GNOME"

Returns :

TRUE if the environment ID is valid

Since 0.2.4


as_utils_is_category_id ()

gboolean            as_utils_is_category_id             (const gchar *category_id);

Searches the known list of registered category IDs.

category_id :

a desktop ID, e.g. "AudioVideoEditing"

Returns :

TRUE if the category ID is valid

Since 0.2.4


as_utils_is_blacklisted_id ()

gboolean            as_utils_is_blacklisted_id          (const gchar *desktop_id);

Searches the known list of blacklisted desktop IDs.

desktop_id :

a desktop ID, e.g. "gimp.desktop"

Returns :

TRUE if the desktop ID is blacklisted

Since 0.2.2


as_utils_spdx_license_tokenize ()

gchar **            as_utils_spdx_license_tokenize      (const gchar *license);

Tokenizes the SPDX license string (or any simarly formatted string) into parts. Any licence parts of the string e.g. "LGPL-2.0+" are prefexed with "@", the conjunctive replaced with "&" and the disjunctive replaced with "|". Brackets are added as indervidual tokens and other strings are appended into single tokens where possible.

license :

a license string, e.g. "LGPLv2+ and (QPL or GPLv2) and MIT"

Returns :

array of strings, or NULL for invalid. [transfer full]

Since 0.1.5


as_utils_spdx_license_detokenize ()

gchar *             as_utils_spdx_license_detokenize    (gchar **license_tokens);

De-tokenizes the SPDX licenses into a string.

license_tokens :

license tokens, typically from as_utils_spdx_license_tokenize()

Returns :

string, or NULL for invalid. [transfer full]

Since 0.2.5


as_utils_license_to_spdx ()

gchar *             as_utils_license_to_spdx            (const gchar *license);

Converts a non-SPDX license into an SPDX format string where possible.

license :

a not-quite SPDX license string, e.g. "GPLv3+"

Returns :

the best-effort SPDX license string

Since 0.5.5


as_utils_find_icon_filename ()

gchar *             as_utils_find_icon_filename         (const gchar *destdir,
                                                         const gchar *search,
                                                         GError **error);

Finds an icon filename from a filesystem root.

destdir :

the destdir.

search :

the icon search name, e.g. "microphone.svg"

error :

A GError or NULL

Returns :

a newly allocated NULL terminated string. [transfer full]

Since 0.2.5


as_utils_find_icon_filename_full ()

gchar *             as_utils_find_icon_filename_full    (const gchar *destdir,
                                                         const gchar *search,
                                                         AsUtilsFindIconFlag flags,
                                                         GError **error);

Finds an icon filename from a filesystem root.

destdir :

the destdir.

search :

the icon search name, e.g. "microphone.svg"

flags :

A AsUtilsFindIconFlag bitfield

error :

A GError or NULL

Returns :

a newly allocated NULL terminated string. [transfer full]

Since 0.3.1


as_utils_install_filename ()

gboolean            as_utils_install_filename           (AsUtilsLocation location,
                                                         const gchar *filename,
                                                         const gchar *origin,
                                                         const gchar *destdir,
                                                         GError **error);

Installs an AppData, MetaInfo, AppStream XML or AppStream Icon metadata file.

location :

the AsUtilsLocation, e.g. AS_UTILS_LOCATION_CACHE

filename :

the full path of the file to install

origin :

the origin to use for the installation, or NULL

destdir :

the destdir to use, or NULL

error :

A GError or NULL

Returns :

TRUE for success, FALSE if error is set

Since 0.3.4


as_utils_search_token_valid ()

gboolean            as_utils_search_token_valid         (const gchar *token);

Checks the search token if it is valid. Valid tokens are at least 3 chars in length, not common words like "and", and do not contain markup.

token :

the search token

Returns :

TRUE is the search token was valid

Since 0.3.4


as_utils_search_tokenize ()

gchar **            as_utils_search_tokenize            (const gchar *search);

Splits up a string into tokens and returns tokens that are suitable for searching. This includes taking out common words and casefolding the returned search tokens.

search :

the search string

Returns :

Valid tokens to search for, or NULL for error. [transfer full]

Since 0.3.4


as_utils_vercmp ()

gint                as_utils_vercmp                     (const gchar *version_a,
                                                         const gchar *version_b);

Compares version numbers for sorting. This function cannot deal with version strings that do not contain numbers, for instance "rev2706" or "1.2_alpha".

version_a :

the release version, e.g. 1.2.3

version_b :

the release version, e.g. 1.2.3.1

Returns :

-1 if a < b, +1 if a > b, 0 if they are equal, and G_MAXINT on error

Since 0.3.5


as_utils_guid_is_valid ()

gboolean            as_utils_guid_is_valid              (const gchar *guid);

Checks the source string is a valid string GUID descriptor.

guid :

string to check

Returns :

TRUE if guid was a valid GUID, FALSE otherwise

Since 0.5.0


as_utils_guid_from_string ()

gchar *             as_utils_guid_from_string           (const gchar *str);

Returns a GUID for a given string. This uses a hash and so even small differences in the str will produce radically different return values.

The implementation is taken from RFC4122, Section 4.1.3; specifically using a type-5 SHA-1 hash with a DNS namespace. The same result can be obtained with this simple python program:

#!/usr/bin/python import uuid print uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')

str :

A source string to use as a key

Returns :

A new GUID, or NULL if the string was invalid

Since 0.5.0


as_utils_guid_from_data ()

gchar *             as_utils_guid_from_data             (const gchar *namespace_id,
                                                         const guint8 *data,
                                                         gsize data_len,
                                                         GError **error);

Returns a GUID for some data. This uses a hash and so even small differences in the data will produce radically different return values.

The implementation is taken from RFC4122, Section 4.1.3; specifically using a type-5 SHA-1 hash.

namespace_id :

A namespace ID, e.g. "6ba7b810-9dad-11d1-80b4-00c04fd430c8"

data :

data to hash

data_len :

length of data

error :

A GError or NULL

Returns :

A new GUID, or NULL if the namespace_id was invalid

Since 0.6.13


as_utils_version_from_uint32 ()

gchar *             as_utils_version_from_uint32        (guint32 val,
                                                         AsVersionParseFlag flags);

Returns a dotted decimal version string from a 32 bit number.

val :

A uint32le version number

flags :

flags used for formatting, e.g. AS_VERSION_PARSE_FLAG_USE_TRIPLET

Returns :

A version number, e.g. "1.0.3"

Since 0.5.2


as_utils_version_from_uint16 ()

gchar *             as_utils_version_from_uint16        (guint16 val,
                                                         AsVersionParseFlag flags);

Returns a dotted decimal version string from a 16 bit number.

val :

A uint16le version number

flags :

flags used for formatting, e.g. AS_VERSION_PARSE_FLAG_USE_TRIPLET

Returns :

A version number, e.g. "1.3"

Since 0.5.2


as_utils_version_parse ()

gchar *             as_utils_version_parse              (const gchar *version);

Returns a dotted decimal version string from a version string. The supported formats are:

  • Dotted decimal, e.g. "1.2.3"

  • Base 16, a hex number *with* a 0x prefix, e.g. "0x10203"

  • Base 10, a string containing just [0-9], e.g. "66051"

  • Date in YYYYMMDD format, e.g. 20150915

Anything with a '.' or that doesn't match [0-9] or 0x[a-f,0-9] is considered a string and returned without modification.

version :

A version number

Returns :

A version number, e.g. "1.0.3"

Since 0.5.2


as_utils_string_replace ()

guint               as_utils_string_replace             (GString *string,
                                                         const gchar *search,
                                                         const gchar *replace);

Performs multiple search and replace operations on the given string.

string :

The GString to operate on

search :

The text to search for

replace :

The text to use for substitutions

Returns :

the number of replacements done, or 0 if search is not found.

Since 0.5.11


as_utils_unique_id_build ()

gchar *             as_utils_unique_id_build            (AsAppScope scope,
                                                         AsBundleKind bundle_kind,
                                                         const gchar *origin,
                                                         AsAppKind kind,
                                                         const gchar *id,
                                                         const gchar *branch);

Builds a valid unique ID using available data.

scope :

a AsAppScope e.g. AS_APP_SCOPE_SYSTEM

bundle_kind :

System, e.g. 'package' or 'flatpak'

origin :

Origin, e.g. 'fedora' or 'gnome-apps-nightly'

kind :

AsAppKind, e.g. AS_APP_KIND_DESKTOP

id :

AppStream ID, e.g. 'gimp.desktop'

branch :

Branch, e.g. '3-20' or 'master'

Returns :

a unique name, or NULL for error;

Since 0.6.1


as_utils_unique_id_equal ()

gboolean            as_utils_unique_id_equal            (const gchar *unique_id1,
                                                         const gchar *unique_id2);

Checks two unique IDs for equality allowing globs to match.

unique_id1 :

a unique ID

unique_id2 :

another unique ID

Returns :

TRUE if the ID's should be considered equal.

Since 0.6.1


as_utils_unique_id_match ()

gboolean            as_utils_unique_id_match            (const gchar *unique_id1,
                                                         const gchar *unique_id2,
                                                         AsUniqueIdMatchFlags match_flags);

Checks two unique IDs for equality allowing globs to match, whilst also allowing clients to whitelist sections that have to match.

unique_id1 :

a unique ID

unique_id2 :

another unique ID

match_flags :

a AsUniqueIdMatchFlags bitfield, e.g. AS_UNIQUE_ID_MATCH_FLAG_ID

Returns :

TRUE if the ID's should be considered equal.

Since 0.7.8


as_utils_unique_id_valid ()

gboolean            as_utils_unique_id_valid            (const gchar *unique_id);

Checks if a unique ID is valid i.e. has the correct number of sections.

unique_id :

a unique ID

Returns :

TRUE if the ID is valid

Since 0.6.1


as_utils_unique_id_hash ()

guint               as_utils_unique_id_hash             (const gchar *unique_id);

Converts a unique-id to a hash value.

This function implements the widely used DJB hash on the ID subset of the unique-id string.

It can be passed to g_hash_table_new() as the hash_func parameter, when using non-NULL strings or unique_ids as keys in a GHashTable.

unique_id :

a unique ID

Returns :

a hash value corresponding to the key

Since 0.6.2


as_utils_appstream_id_build ()

gchar *             as_utils_appstream_id_build         (const gchar *str);

Fixes a string to be a valid AppStream ID.

This function replaces any invalid chars with an underscore.

str :

a string to build the AppStream ID from

Returns :

a valid AppStream ID, or NULL if str is invalid

Since 0.6.4


as_utils_appstream_id_valid ()

gboolean            as_utils_appstream_id_valid         (const gchar *str);

Checks to see if a string is a valid AppStream ID. A valid AppStream ID only contains alpha-numeric chars, dots and dashes.

str :

a string

Returns :

TRUE if the string is a valid AppStream ID

Since 0.6.4