manpagez: man pages & more
html files: appstream-glib
Home | html | info | man

as-utils

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

Stability Level

Stable, unless otherwise indicated

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

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

 
© manpagez.com 2000-2017
Individual documents may contain additional copyright information.