as-utils

as-utils — Helper functions that are used inside libappstream

Functions

Types and Values

Includes

#include <appstream.h>

Description

Functions which are used in libappstream and might be useful for others as well.

Functions

as_utils_error_quark ()

GQuark
as_utils_error_quark (void);

Returns

An error quark.

Since: 0.14.0


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


as_markup_convert_simple ()

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

as_utils_locale_is_compatible ()

gboolean
as_utils_locale_is_compatible (const gchar *locale1,
                               const gchar *locale2);

Calculates if one locale is compatible with another. When doing the calculation the locale and language code is taken into account if possible.

Parameters

locale1

a locale string, or NULL

 

locale2

a locale string, or NULL

 

Returns

TRUE if the locale is compatible.

Since: 0.9.5


as_utils_is_category_name ()

gboolean
as_utils_is_category_name (const gchar *category_name);

as_utils_is_tld ()

gboolean
as_utils_is_tld (const gchar *tld);

Searches the known list of TLDs we allow for AppStream IDs. This excludes internationalized names.

Parameters

tld

a top-level domain without dot, e.g. "de", "org", "name"

 

Returns

TRUE if the TLD is valid

Since: 0.9.8


as_utils_is_desktop_environment ()

gboolean
as_utils_is_desktop_environment (const gchar *desktop);

Searches the known list of desktop environments AppStream knows about.

Parameters

desktop

a desktop environment id.

 

Returns

TRUE if the desktop-id is valid

Since: 0.10.0


as_utils_sort_components_into_categories ()

void
as_utils_sort_components_into_categories
                               (GPtrArray *cpts,
                                GPtrArray *categories,
                                gboolean check_duplicates);

Sorts all components in cpts into the AsCategory categories listed in categories .

Parameters

cpts

List of components.

[element-type AsComponent]

categories

List of categories to sort components into.

[element-type AsCategory]

check_duplicates

Whether to check for duplicates.

 

as_utils_build_data_id ()

gchar *
as_utils_build_data_id (AsComponentScope scope,
                        AsBundleKind bundle_kind,
                        const gchar *origin,
                        const gchar *cid,
                        const gchar *branch);

Builds an identifier string unique to the individual dataset using the supplied information.

Parameters

scope

Scope of the metadata as AsComponentScope e.g. AS_COMPONENT_SCOPE_SYSTEM

 

bundle_kind

Bundling system providing this data, e.g. 'package' or 'flatpak'

 

origin

Origin string, e.g. 'os' or 'gnome-apps-nightly'

 

cid

AppStream component ID, e.g. 'org.freedesktop.appstream.cli'

 

branch

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

 

Since: 0.14.0


as_utils_data_id_valid ()

gboolean
as_utils_data_id_valid (const gchar *data_id);

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

Parameters

data_id

a component data ID

 

Returns

TRUE if the ID is valid

Since: 0.14.0


as_utils_data_id_get_cid ()

gchar *
as_utils_data_id_get_cid (const gchar *data_id);

Get the component-id part of the data-id.

Parameters

data_id

The data-id.

 

as_utils_data_id_match ()

gboolean
as_utils_data_id_match (const gchar *data_id1,
                        const gchar *data_id2,
                        AsDataIdMatchFlags match_flags);

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

Parameters

data_id1

a data ID

 

data_id2

another data ID

 

match_flags

a AsDataIdMatchFlags bitfield, e.g. AS_DATA_ID_MATCH_FLAG_ID

 

Returns

TRUE if the IDs should be considered equal.

Since: 0.14.0


as_utils_data_id_equal ()

gboolean
as_utils_data_id_equal (const gchar *data_id1,
                        const gchar *data_id2);

Checks two component data IDs for equality allowing globs to match.

Parameters

data_id1

a data ID

 

data_id2

another data ID

 

Returns

TRUE if the ID's should be considered equal.

Since: 0.14.0


as_utils_data_id_hash ()

guint
as_utils_data_id_hash (const gchar *data_id);

Converts a data-id to a hash value.

This function implements the widely used DJB hash on the ID subset of the data-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

data_id

a data ID

 

Returns

a hash value corresponding to the key

Since: 0.14.0


as_gstring_replace ()

guint
as_gstring_replace (GString *string,
                    const gchar *find,
                    const gchar *replace);

Replaces all occurences of find with the string replace in a GString.

Parameters

string

a GString

 

find

the string to find in string

 

replace

the string to insert in place of find

 

Returns

the number of find and replace operations performed.


as_gstring_replace2 ()

guint
as_gstring_replace2 (GString *string,
                     const gchar *find,
                     const gchar *replace,
                     guint limit);

Replaces the string find with the string replace in a GString up to limit times. If the number of instances of find in the GString is less than limit , all instances are replaced. If limit is 0, all instances of find are replaced.

Parameters

string

a GString

 

find

the string to find in string

 

replace

the string to insert in place of find

 

limit

the maximum instances of find to replace with replace , or 0 for no limit

 

Returns

the number of find and replace operations performed.


as_utils_is_platform_triplet ()

gboolean
as_utils_is_platform_triplet (const gchar *triplet);

Test if the given string is a valid platform triplet recognized by AppStream.

Parameters

triplet

a platform triplet.

 

Returns

TRUE if triplet is valid.

Since: 0.14.0


as_utils_install_metadata_file ()

gboolean
as_utils_install_metadata_file (AsMetadataLocation location,
                                const gchar *filename,
                                const gchar *origin,
                                const gchar *destdir,
                                GError **error);

Installs an AppStream MetaInfo, AppStream Metadata Catalog or AppStream Icon tarball file to the right place on the filesystem. Please note that this function does almost no validation and may guess missing values such as icon sizes and origin names. Ensure your metadata is good before installing it.

Parameters

location

the AsMetadataLocation, e.g. AS_METADATA_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.14.0


as_utils_guess_scope_from_path ()

AsComponentScope
as_utils_guess_scope_from_path (const gchar *path);

Guess the AsComponentScope that applies to a given path.

Parameters

path

The filename to test.

 

Returns

the AsComponentScope

Since: 0.15.0


as_get_appstream_version ()

const gchar *
as_get_appstream_version (void);

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

Get the version of the AppStream library that is currently used as a string.

Returns

The AppStream version.

Types and Values

enum AsUtilsError

The error type.

Members

AS_UTILS_ERROR_FAILED

Generic failure

 

AS_UTILS_ERROR

#define AS_UTILS_ERROR				as_utils_error_quark ()

enum AsDataIdMatchFlags

The flags used when matching unique IDs.

Members

AS_DATA_ID_MATCH_FLAG_NONE

No flags set

 

AS_DATA_ID_MATCH_FLAG_SCOPE

Scope, e.g. a AsComponentScope

 

AS_DATA_ID_MATCH_FLAG_BUNDLE_KIND

Bundle kind, e.g. a AsBundleKind

 

AS_DATA_ID_MATCH_FLAG_ORIGIN

Origin

 

AS_DATA_ID_MATCH_FLAG_ID

Component AppStream ID

 

AS_DATA_ID_MATCH_FLAG_BRANCH

Branch

 

enum AsMetadataLocation

The flags used when installing and removing metadata files.

Members

AS_METADATA_LOCATION_SHARED

Installed by the vendor, shared

 

AS_METADATA_LOCATION_STATE

Installed as metadata into /var/lib, shared

 

AS_METADATA_LOCATION_CACHE

Installed as metadata into /var/cache, shared

 

AS_METADATA_LOCATION_USER

Installed for the current user