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,
                          gssize markup_len,
                          GError **error);

Converts an XML description into a printable form.

Parameters

markup

the text to copy.

 

markup_len

the length of markup , or -1 if markup is NULL terminated.

 

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,
                   gssize markup_len,
                   AsMarkupConvertFormat format,
                   GError **error);

Converts an XML description into a printable form.

Parameters

markup

the text to copy.

 

markup_len

the length of markup , or -1 if markup is NULL terminated.

 

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_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_check_url_exists ()

gboolean
as_utils_check_url_exists (const gchar *url,
                           guint timeout,
                           GError **error);

Checks to see if a URL is reachable.

Parameters

url

the URL to check.

 

timeout

the timeout in seconds.

 

error

A GError or NULL

 

Returns

TRUE if the URL was reachable and pointed to a non-zero-length file.

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

gchar *
as_utils_get_string_overlap (const gchar *s1,
                             const gchar *s2);

Return a prefix and sufffix that is common to both strings.

Parameters

s1

A string.

 

s2

Another string

 

Returns

a newly allocated NULL terminated string, or NULL.

[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

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

   

AS_MARKUP_CONVERT_FORMAT_MARKDOWN

Markdown format