as-utils: AppStream-glib Reference Manual

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

## Stability Level

Stable, unless otherwise indicated

## Functions

GQuark | as_utils_error_quark ()
gboolean | as_utils_is_stock_icon_name ()
gboolean | as_utils_is_spdx_license_id ()
gboolean | as_utils_is_spdx_license ()
gboolean | as_utils_is_environment_id ()
gboolean | as_utils_is_category_id ()
gboolean | as_utils_is_blacklisted_id ()
gchar ** | as_utils_spdx_license_tokenize ()
gchar * | as_utils_spdx_license_detokenize ()
gchar * | as_utils_license_to_spdx ()
gchar * | as_utils_find_icon_filename ()
gchar * | as_utils_find_icon_filename_full ()
gboolean | as_utils_install_filename ()
gboolean | as_utils_search_token_valid ()
gchar ** | as_utils_search_tokenize ()
gint | as_utils_vercmp_full ()
gint | as_utils_vercmp ()
gboolean | as_utils_guid_is_valid ()
gchar * | as_utils_guid_from_string ()
gchar * | as_utils_guid_from_data ()
gchar * | as_utils_version_from_uint32 ()
gchar * | as_utils_version_from_uint16 ()
gchar * | as_utils_version_parse ()
guint | as_utils_string_replace ()
gchar * | as_utils_unique_id_build ()
gboolean | as_utils_unique_id_equal ()
gboolean | as_utils_unique_id_match ()
gboolean | as_utils_unique_id_valid ()
guint | as_utils_unique_id_hash ()
gchar * | as_utils_appstream_id_build ()
gboolean | as_utils_appstream_id_valid ()

## Types and Values

enum | AsUtilsError
#define | AS_UTILS_ERROR
enum | AsUtilsFindIconFlag
enum | AsUtilsLocation
enum | AsVersionParseFlag
enum | AsVersionCompareFlag
enum | AsUniqueIdMatchFlags

## Includes

    #include <appstream-glib.h>

## Description

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

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

`as_utils_is_blacklisted_id` is deprecated and should not be used in newly-written code.

Searches the known list of blacklisted desktop IDs.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

search | the search string |

#### Returns

Valid tokens to search for, or `NULL` for error.

[transfer full]

Since: 0.3.4

### as_utils_vercmp_full ()

    gint
    as_utils_vercmp_full (const gchar *version_a,
                          const gchar *version_b,
                          AsVersionCompareFlag flags);

Compares version numbers for sorting.

#### Parameters

version_a | the release version, e.g. 1.2.3 |
version_b | the release version, e.g. 1.2.3.1 |
flags | some AsVersionCompareFlag |

#### Returns

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

Since: 0.7.15

### as_utils_vercmp ()

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

Compares version numbers for sorting.

#### Parameters

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.

#### Parameters

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')

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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 alphanumeric chars, dots and dashes.

#### Parameters

str | a string |

#### Returns

`TRUE` if the string is a valid AppStream ID

Since: 0.6.4

## Types and Values

### enum AsUtilsError

The error type.

#### Members

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

The flags used when finding icons.

#### Members

AS_UTILS_FIND_ICON_NONE | No flags set |
AS_UTILS_FIND_ICON_HI_DPI | Prefer a HiDPI icon |

### enum AsUtilsLocation

The flags used when installing and removing metadata files.

#### Members

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

The flags used when parsing version numbers.

#### Members

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 AsVersionCompareFlag

The flags used when comparing version numbers.

#### Members

AS_VERSION_COMPARE_FLAG_NONE | No flags set |
AS_VERSION_COMPARE_FLAG_USE_HEURISTICS | Use a heuristic to parse version numbers |

### enum AsUniqueIdMatchFlags

The flags used when matching unique IDs.

#### Members

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 |