![]() |
![]() |
![]() |
AppStream-glib Reference Manual | |
---|---|---|---|---|
Top | Description |
#include <appstream-glib.h> enum AsUtilsError; #define AS_UTILS_ERROR enum AsUtilsFindIconFlag; enum AsUtilsLocation; enum AsVersionParseFlag; enum AsUniqueIdMatchFlags; GQuark as_utils_error_quark (void
); gboolean as_utils_is_stock_icon_name (const gchar *name
); gboolean as_utils_is_spdx_license_id (const gchar *license_id
); gboolean as_utils_is_spdx_license (const gchar *license
); gboolean as_utils_is_environment_id (const gchar *environment_id
); gboolean as_utils_is_category_id (const gchar *category_id
); gboolean as_utils_is_blacklisted_id (const gchar *desktop_id
); gchar ** as_utils_spdx_license_tokenize (const gchar *license
); gchar * as_utils_spdx_license_detokenize (gchar **license_tokens
); gchar * as_utils_license_to_spdx (const gchar *license
); gchar * as_utils_find_icon_filename (const gchar *destdir
,const gchar *search
,GError **error
); gchar * as_utils_find_icon_filename_full (const gchar *destdir
,const gchar *search
,AsUtilsFindIconFlag flags
,GError **error
); gboolean as_utils_install_filename (AsUtilsLocation location
,const gchar *filename
,const gchar *origin
,const gchar *destdir
,GError **error
); gboolean as_utils_search_token_valid (const gchar *token
); gchar ** as_utils_search_tokenize (const gchar *search
); gint as_utils_vercmp (const gchar *version_a
,const gchar *version_b
); gboolean as_utils_guid_is_valid (const gchar *guid
); gchar * as_utils_guid_from_string (const gchar *str
); gchar * as_utils_guid_from_data (const gchar *namespace_id
,const guint8 *data
,gsize data_len
,GError **error
); gchar * as_utils_version_from_uint32 (guint32 val
,AsVersionParseFlag flags
); gchar * as_utils_version_from_uint16 (guint16 val
,AsVersionParseFlag flags
); gchar * as_utils_version_parse (const gchar *version
); guint as_utils_string_replace (GString *string
,const gchar *search
,const gchar *replace
); gchar * as_utils_unique_id_build (AsAppScope scope
,AsBundleKind bundle_kind
,const gchar *origin
,AsAppKind kind
,const gchar *id
,const gchar *branch
); gboolean as_utils_unique_id_equal (const gchar *unique_id1
,const gchar *unique_id2
); gboolean as_utils_unique_id_match (const gchar *unique_id1
,const gchar *unique_id2
,AsUniqueIdMatchFlags match_flags
); gboolean as_utils_unique_id_valid (const gchar *unique_id
); guint as_utils_unique_id_hash (const gchar *unique_id
); gchar * as_utils_appstream_id_build (const gchar *str
); gboolean as_utils_appstream_id_valid (const gchar *str
);
These functions are used internally to libappstream-glib, and some may be useful to user-applications.
typedef enum { AS_UTILS_ERROR_FAILED, AS_UTILS_ERROR_INVALID_TYPE, } AsUtilsError;
The error type.
typedef enum { AS_UTILS_FIND_ICON_NONE = 0, AS_UTILS_FIND_ICON_HI_DPI = 1 << 0, } AsUtilsFindIconFlag;
The flags used when finding icons.
typedef enum { AS_UTILS_LOCATION_SHARED, AS_UTILS_LOCATION_CACHE, AS_UTILS_LOCATION_USER, } AsUtilsLocation;
The flags used when installing and removing metadata files.
typedef enum { AS_VERSION_PARSE_FLAG_NONE = 0, AS_VERSION_PARSE_FLAG_USE_TRIPLET = 1 << 0, AS_VERSION_PARSE_FLAG_USE_BCD = 1 << 1, /* Since: 0.7.3 */ } AsVersionParseFlag;
The flags used when parsing version numbers.
typedef enum { AS_UNIQUE_ID_MATCH_FLAG_NONE = 0, AS_UNIQUE_ID_MATCH_FLAG_SCOPE = 1 << 0, AS_UNIQUE_ID_MATCH_FLAG_BUNDLE_KIND = 1 << 1, /* Since: 0.7.8 */ AS_UNIQUE_ID_MATCH_FLAG_ORIGIN = 1 << 2, /* Since: 0.7.8 */ AS_UNIQUE_ID_MATCH_FLAG_KIND = 1 << 3, /* Since: 0.7.8 */ AS_UNIQUE_ID_MATCH_FLAG_ID = 1 << 4, /* Since: 0.7.8 */ AS_UNIQUE_ID_MATCH_FLAG_BRANCH = 1 << 5, /* Since: 0.7.8 */ } AsUniqueIdMatchFlags;
The flags used when matching unique IDs.
No flags set | |
Scope, e.g. a AsAppScope | |
Bundle kind, e.g. a AsBundleKind | |
Origin | |
Component kind, e.g. a AsAppKind | |
Component AppStream ID | |
Branch |
gboolean as_utils_is_stock_icon_name (const gchar *name
);
Searches the known list of stock icons.
|
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
gboolean as_utils_is_spdx_license_id (const gchar *license_id
);
Searches the known list of SPDX license IDs.
|
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
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.
|
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
gboolean as_utils_is_environment_id (const gchar *environment_id
);
Searches the known list of registered environment IDs.
|
a desktop ID, e.g. "GNOME" |
Returns : |
TRUE if the environment ID is valid |
Since 0.2.4
gboolean as_utils_is_category_id (const gchar *category_id
);
Searches the known list of registered category IDs.
|
a desktop ID, e.g. "AudioVideoEditing" |
Returns : |
TRUE if the category ID is valid |
Since 0.2.4
gboolean as_utils_is_blacklisted_id (const gchar *desktop_id
);
Searches the known list of blacklisted desktop IDs.
|
a desktop ID, e.g. "gimp.desktop" |
Returns : |
TRUE if the desktop ID is blacklisted |
Since 0.2.2
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.
|
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
gchar * as_utils_spdx_license_detokenize (gchar **license_tokens
);
De-tokenizes the SPDX licenses into a string.
|
license tokens, typically from as_utils_spdx_license_tokenize()
|
Returns : |
string, or NULL for invalid. [transfer full]
|
Since 0.2.5
gchar * as_utils_license_to_spdx (const gchar *license
);
Converts a non-SPDX license into an SPDX format string where possible.
|
a not-quite SPDX license string, e.g. "GPLv3+" |
Returns : |
the best-effort SPDX license string |
Since 0.5.5
gchar * as_utils_find_icon_filename (const gchar *destdir
,const gchar *search
,GError **error
);
Finds an icon filename from a filesystem root.
|
the destdir. |
|
the icon search name, e.g. "microphone.svg" |
|
A GError or NULL
|
Returns : |
a newly allocated NULL terminated string. [transfer full]
|
Since 0.2.5
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.
|
the destdir. |
|
the icon search name, e.g. "microphone.svg" |
|
A AsUtilsFindIconFlag bitfield |
|
A GError or NULL
|
Returns : |
a newly allocated NULL terminated string. [transfer full]
|
Since 0.3.1
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.
|
the AsUtilsLocation, e.g. AS_UTILS_LOCATION_CACHE
|
|
the full path of the file to install |
|
the origin to use for the installation, or NULL
|
|
the destdir to use, or NULL
|
|
A GError or NULL
|
Returns : |
TRUE for success, FALSE if error is set |
Since 0.3.4
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.
|
the search token |
Returns : |
TRUE is the search token was valid |
Since 0.3.4
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.
|
the search string |
Returns : |
Valid tokens to search for, or NULL for error. [transfer full]
|
Since 0.3.4
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".
|
the release version, e.g. 1.2.3 |
|
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
gboolean as_utils_guid_is_valid (const gchar *guid
);
Checks the source string is a valid string GUID descriptor.
|
string to check |
Returns : |
TRUE if guid was a valid GUID, FALSE otherwise |
Since 0.5.0
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')
|
A source string to use as a key |
Returns : |
A new GUID, or NULL if the string was invalid |
Since 0.5.0
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.
|
A namespace ID, e.g. "6ba7b810-9dad-11d1-80b4-00c04fd430c8" |
|
data to hash |
|
length of data
|
|
A GError or NULL
|
Returns : |
A new GUID, or NULL if the namespace_id was invalid |
Since 0.6.13
gchar * as_utils_version_from_uint32 (guint32 val
,AsVersionParseFlag flags
);
Returns a dotted decimal version string from a 32 bit number.
|
A uint32le version number |
|
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
gchar * as_utils_version_from_uint16 (guint16 val
,AsVersionParseFlag flags
);
Returns a dotted decimal version string from a 16 bit number.
|
A uint16le version number |
|
flags used for formatting, e.g. AS_VERSION_PARSE_FLAG_USE_TRIPLET
|
Returns : |
A version number, e.g. "1.3" |
Since 0.5.2
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.
|
A version number |
Returns : |
A version number, e.g. "1.0.3" |
Since 0.5.2
guint as_utils_string_replace (GString *string
,const gchar *search
,const gchar *replace
);
Performs multiple search and replace operations on the given string.
|
The GString to operate on |
|
The text to search for |
|
The text to use for substitutions |
Returns : |
the number of replacements done, or 0 if search is not found. |
Since 0.5.11
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.
|
a AsAppScope e.g. AS_APP_SCOPE_SYSTEM
|
|
System, e.g. 'package' or 'flatpak' |
|
Origin, e.g. 'fedora' or 'gnome-apps-nightly' |
|
AsAppKind, e.g. AS_APP_KIND_DESKTOP
|
|
AppStream ID, e.g. 'gimp.desktop' |
|
Branch, e.g. '3-20' or 'master' |
Returns : |
a unique name, or NULL for error; |
Since 0.6.1
gboolean as_utils_unique_id_equal (const gchar *unique_id1
,const gchar *unique_id2
);
Checks two unique IDs for equality allowing globs to match.
|
a unique ID |
|
another unique ID |
Returns : |
TRUE if the ID's should be considered equal. |
Since 0.6.1
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.
|
a unique ID |
|
another unique ID |
|
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
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.
|
a unique ID |
Returns : |
TRUE if the ID is valid |
Since 0.6.1
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.
|
a unique ID |
Returns : |
a hash value corresponding to the key |
Since 0.6.2
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.
|
a string to build the AppStream ID from |
Returns : |
a valid AppStream ID, or NULL if str is invalid |
Since 0.6.4