as-utils

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

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

Includes

#include <appstream-glib.h>

Description

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

Functions

as_markup_convert_simple ()

gchar *
as_markup_convert_simple (const gchar *markup,
                          GError **error);

Converts an XML description into a printable form.

Parameters

markup

the text to copy.

 

error

A GError or NULL

 

Returns

a newly allocated NULL terminated string.

[transfer full]

Since: 0.1.0


as_markup_convert ()

gchar *
as_markup_convert (const gchar *markup,
                   AsMarkupConvertFormat format,
                   GError **error);

Converts an XML description into a printable form.

Parameters

markup

the text to copy.

 

format

the AsMarkupConvertFormat, e.g. AS_MARKUP_CONVERT_FORMAT_MARKDOWN

 

error

A GError or NULL

 

Returns

a newly allocated NULL terminated string.

[transfer full]

Since: 0.3.5


as_markup_convert_full ()

gchar *
as_markup_convert_full (const gchar *markup,
                        AsMarkupConvertFormat format,
                        AsMarkupConvertFlag flags,
                        GError **error);

Converts an XML description into a printable form.

Parameters

markup

the text to copy.

 

format

the AsMarkupConvertFormat, e.g. AS_MARKUP_CONVERT_FORMAT_MARKDOWN

 

flags

the AsMarkupConvertFlag, e.g. AS_MARKUP_CONVERT_FLAG_IGNORE_ERRORS

 

error

A GError or NULL

 

Returns

a newly allocated NULL terminated string.

[transfer full]

Since: 0.3.5


as_markup_validate ()

gboolean
as_markup_validate (const gchar *markup,
                    GError **error);

Validates some markup.

Parameters

markup

the text to validate

 

error

A GError or NULL

 

Returns

TRUE if the appstream description was valid

Since: 0.5.1


as_markup_strsplit_words ()

gchar **
as_markup_strsplit_words (const gchar *text,
                          guint line_len);

Splits up a long line into an array of smaller strings, each being no longer than line_len . Words are not split.

Parameters

text

the text to split.

 

line_len

the maximum length of the output line

 

Returns

lines, or NULL in event of an error.

[transfer full]

Since: 0.3.5


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

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.

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

[transfer full]

Since: 0.2.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 ()

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

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

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 AsMarkupConvertFormat

The output format used when converting AppStream descriptions.

Members

AS_MARKUP_CONVERT_FORMAT_SIMPLE

UTF-8 text

 

AS_MARKUP_CONVERT_FORMAT_MARKDOWN

Markdown format

 

AS_MARKUP_CONVERT_FORMAT_NULL

No output

 

AS_MARKUP_CONVERT_FORMAT_APPSTREAM

AppStream (passthrough)

 

enum AsMarkupConvertFlag

The flags used when converting descriptions from AppStream-style.

Members

AS_MARKUP_CONVERT_FLAG_NONE

No flags set

 

AS_MARKUP_CONVERT_FLAG_IGNORE_ERRORS

Ignore errors where possible

 

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