libappstream/auto/

functions.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from
// from gir-files (https://github.com/gtk-rs/gir-files.git)
// DO NOT EDIT

use crate::{
    ffi, BundleKind, Category, Component, ComponentScope, DataIdMatchFlags, MarkupKind,
    MetadataLocation, RelationCompare, VercmpFlags,
};
use glib::translate::*;

/// Returns the component-ID of the current distribution based on contents
/// of the `/etc/os-release` file.
/// This function is a shorthand for `as_distro_details_get_cid`
#[doc(alias = "as_get_current_distro_component_id")]
#[doc(alias = "get_current_distro_component_id")]
pub fn current_distro_component_id() -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe { from_glib_full(ffi::as_get_current_distro_component_id()) }
}

/// Get a list of the default Freedesktop and AppStream categories
/// that software components (especially GUI applications) can be sorted
/// into in software centers.
/// ## `with_special`
/// Include special categories (e.g. "addons", and "all"/"featured" in submenus)
///
/// # Returns
///
/// a list of [`Category`][crate::Category]
#[doc(alias = "as_get_default_categories")]
#[doc(alias = "get_default_categories")]
pub fn default_categories(with_special: bool) -> Vec<Category> {
    assert_initialized_main_thread!();
    unsafe {
        FromGlibPtrContainer::from_glib_container(ffi::as_get_default_categories(
            with_special.into_glib(),
        ))
    }
}

/// Get a list of the default Freedesktop and AppStream categories
/// that software components (especially GUI applications) can be sorted
/// into in software centers.
///
/// This function fully transfers ownership of the returned container,
/// to be used in GIR bindings.
/// ## `with_special`
/// Include special categories (e.g. "addons", and "all"/"featured" in submenus)
///
/// # Returns
///
/// a list of [`Category`][crate::Category]
#[doc(alias = "as_get_default_categories_gi")]
#[doc(alias = "get_default_categories_gi")]
pub fn default_categories_gi(with_special: bool) -> Vec<Category> {
    assert_initialized_main_thread!();
    unsafe {
        FromGlibPtrContainer::from_glib_full(ffi::as_get_default_categories_gi(
            with_special.into_glib(),
        ))
    }
}

/// Get a translated license name for the given SPDX ID.
/// ## `license`
/// The SPDX license ID.
///
/// # Returns
///
/// The license name, or [`None`] if none found.
#[doc(alias = "as_get_license_name")]
#[doc(alias = "get_license_name")]
pub fn license_name(license: &str) -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe { from_glib_full(ffi::as_get_license_name(license.to_glib_none().0)) }
}

/// Get a web URL to the license text and more license information for an SPDX
/// license identifier.
/// ## `license`
/// The SPDX license ID.
///
/// # Returns
///
/// The license URL, or [`None`] if none available.
#[doc(alias = "as_get_license_url")]
#[doc(alias = "get_license_url")]
pub fn license_url(license: &str) -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe { from_glib_full(ffi::as_get_license_url(license.to_glib_none().0)) }
}

/// Searches the known list of SPDX license exception IDs.
/// ## `exception_id`
/// a single SPDX license exception ID, e.g. "GCC-exception-3.1"
///
/// # Returns
///
/// [`true`] if the string is a valid SPDX license exception ID
#[doc(alias = "as_is_spdx_license_exception_id")]
pub fn is_spdx_license_exception_id(exception_id: &str) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::as_is_spdx_license_exception_id(
            exception_id.to_glib_none().0,
        ))
    }
}

/// Checks the licence string to check it being a valid licence.
/// NOTE: SPDX licenses can't typically contain brackets.
/// ## `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"
#[doc(alias = "as_is_spdx_license_expression")]
pub fn is_spdx_license_expression(license: &str) -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::as_is_spdx_license_expression(license.to_glib_none().0)) }
}

/// Searches the known list of SPDX license IDs.
/// ## `license_id`
/// a single SPDX license ID, e.g. "GPL-3.0"
///
/// # Returns
///
/// [`true`] if the string is a valid SPDX license ID
#[doc(alias = "as_is_spdx_license_id")]
pub fn is_spdx_license_id(license_id: &str) -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::as_is_spdx_license_id(license_id.to_glib_none().0)) }
}

/// Check if the given license is for free-as-in-freedom software.
/// A free software license is either approved by the Free Software Foundation
/// or the Open Source Initiative.
///
/// This function does *not* yet handle complex license expressions with AND and OR.
/// If the expression contains any of these, it will still simply check if all mentioned
/// licenses are Free licenses.
/// Currently, any license exception recognized by SPDX is assumed to not impact the free-ness
/// status of a software component.
///
/// Please note that this function does not give any legal advice. Please read the license texts
/// to learn more about the individual licenses and their conditions.
/// ## `license`
/// The SPDX license string to test.
///
/// # Returns
///
/// [`true`] if the license string contains only free-as-in-freedom licenses.
#[doc(alias = "as_license_is_free_license")]
pub fn license_is_free_license(license: &str) -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::as_license_is_free_license(license.to_glib_none().0)) }
}

/// Check if the metadata license is suitable for mixing with other
/// metadata and redistributing the bundled result (this means we
/// prefer permissive licenses here, to not require people shipping
/// catalog metadata to perform a full license review).
///
/// This method checks against a hardcoded list of permissive licenses
/// commonly used to license metadata under.
/// ## `license`
/// The SPDX license string to test.
///
/// # Returns
///
/// [`true`] if the license contains only permissive licenses suitable
/// as metadata license.
#[doc(alias = "as_license_is_metadata_license")]
pub fn license_is_metadata_license(license: &str) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::as_license_is_metadata_license(
            license.to_glib_none().0,
        ))
    }
}

/// Tests license ID against the vetted list of licenses that
/// can be used for metainfo metadata.
/// This function will not work for license expressions, if you need
/// to test an SPDX license expression for compliance, please
/// use `as_license_is_metadata_license` insread.
/// ## `license_id`
/// a single SPDX license ID, e.g. "FSFAP"
///
/// # Returns
///
/// [`true`] if the string is a valid metadata license ID.
#[doc(alias = "as_license_is_metadata_license_id")]
pub fn license_is_metadata_license_id(license_id: &str) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::as_license_is_metadata_license_id(
            license_id.to_glib_none().0,
        ))
    }
}

/// Converts a non-SPDX license into an SPDX format string where possible.
/// ## `license`
/// a not-quite SPDX license string, e.g. "GPLv3+"
///
/// # Returns
///
/// the best-effort SPDX license string
#[doc(alias = "as_license_to_spdx_id")]
pub fn license_to_spdx_id(license: &str) -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe { from_glib_full(ffi::as_license_to_spdx_id(license.to_glib_none().0)) }
}

/// Converts XML description markup into other forms of text.
/// ## `markup`
/// the XML markup to transform.
/// ## `to_kind`
/// The markup style to convert into.
///
/// # Returns
///
/// a newly allocated string, or [`None`] on error.
#[doc(alias = "as_markup_convert")]
pub fn markup_convert(markup: &str, to_kind: MarkupKind) -> Result<glib::GString, glib::Error> {
    assert_initialized_main_thread!();
    unsafe {
        let mut error = std::ptr::null_mut();
        let ret = ffi::as_markup_convert(markup.to_glib_none().0, to_kind.into_glib(), &mut error);
        if error.is_null() {
            Ok(from_glib_full(ret))
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// Splits up a long line into an array of smaller strings, each being no longer
/// than `line_len`. Words are not split.
/// ## `text`
/// the text to split.
/// ## `line_len`
/// the maximum length of the output line
///
/// # Returns
///
/// lines, or [`None`] in event of an error
#[doc(alias = "as_markup_strsplit_words")]
pub fn markup_strsplit_words(text: &str) -> Vec<glib::GString> {
    assert_initialized_main_thread!();
    let line_len = text.len() as _;
    unsafe {
        FromGlibPtrContainer::from_glib_full(ffi::as_markup_strsplit_words(
            text.to_glib_none().0,
            line_len,
        ))
    }
}

/// Tokenizes the SPDX license string (or any simarly formatted string)
/// into parts. Any license parts of the string e.g. "LGPL-2.0+" are prefexed
/// with "@", the conjunctive replaced with "&", the disjunctive replaced
/// with "|" and the WITH operator for license exceptions replaced with "^".
/// Brackets are added as indervidual tokens and other strings are
/// appended into single tokens where possible.
/// ## `license`
/// a license string, e.g. "LGPLv2+ and (QPL or GPLv2) and MIT"
///
/// # Returns
///
/// array of strings, or [`None`] for invalid
#[doc(alias = "as_spdx_license_tokenize")]
pub fn spdx_license_tokenize(license: &str) -> Vec<glib::GString> {
    assert_initialized_main_thread!();
    unsafe {
        FromGlibPtrContainer::from_glib_full(ffi::as_spdx_license_tokenize(
            license.to_glib_none().0,
        ))
    }
}

/// Builds an identifier string unique to the individual dataset using the supplied information.
/// ## `scope`
/// Scope of the metadata as [`ComponentScope`][crate::ComponentScope] e.g. [`ComponentScope::System`][crate::ComponentScope::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'
#[doc(alias = "as_utils_build_data_id")]
pub fn utils_build_data_id(
    scope: ComponentScope,
    bundle_kind: BundleKind,
    origin: &str,
    cid: &str,
    branch: &str,
) -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe {
        from_glib_full(ffi::as_utils_build_data_id(
            scope.into_glib(),
            bundle_kind.into_glib(),
            origin.to_glib_none().0,
            cid.to_glib_none().0,
            branch.to_glib_none().0,
        ))
    }
}

#[doc(alias = "as_utils_data_id_equal")]
pub fn utils_data_id_equal(data_id1: &str, data_id2: &str) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::as_utils_data_id_equal(
            data_id1.to_glib_none().0,
            data_id2.to_glib_none().0,
        ))
    }
}

/// Get the component-id part of the data-id.
/// ## `data_id`
/// The data-id.
#[doc(alias = "as_utils_data_id_get_cid")]
pub fn utils_data_id_get_cid(data_id: &str) -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe { from_glib_full(ffi::as_utils_data_id_get_cid(data_id.to_glib_none().0)) }
}

#[doc(alias = "as_utils_data_id_hash")]
pub fn utils_data_id_hash(data_id: &str) -> u32 {
    assert_initialized_main_thread!();
    unsafe { ffi::as_utils_data_id_hash(data_id.to_glib_none().0) }
}

/// Checks two data IDs for equality allowing globs to match, whilst also
/// allowing clients to whitelist sections that have to match.
/// ## `data_id1`
/// a data ID
/// ## `data_id2`
/// another data ID
/// ## `match_flags`
/// a [`DataIdMatchFlags`][crate::DataIdMatchFlags] bitfield, e.g. [`DataIdMatchFlags::ID`][crate::DataIdMatchFlags::ID]
///
/// # Returns
///
/// [`true`] if the IDs should be considered equal.
#[doc(alias = "as_utils_data_id_match")]
pub fn utils_data_id_match(data_id1: &str, data_id2: &str, match_flags: DataIdMatchFlags) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::as_utils_data_id_match(
            data_id1.to_glib_none().0,
            data_id2.to_glib_none().0,
            match_flags.into_glib(),
        ))
    }
}

/// Checks if a data ID is valid i.e. has the correct number of
/// sections.
/// ## `data_id`
/// a component data ID
///
/// # Returns
///
/// [`true`] if the ID is valid
#[doc(alias = "as_utils_data_id_valid")]
pub fn utils_data_id_valid(data_id: &str) -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::as_utils_data_id_valid(data_id.to_glib_none().0)) }
}

/// Get a human-readable, translated name of the desktop environment
/// represented by the given ID.
/// ## `de_id`
/// a desktop environment id.
///
/// # Returns
///
/// A localized name of the DE, or [`None`] if none available.
#[doc(alias = "as_utils_get_desktop_environment_name")]
pub fn utils_get_desktop_environment_name(de_id: &str) -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe {
        from_glib_none(ffi::as_utils_get_desktop_environment_name(
            de_id.to_glib_none().0,
        ))
    }
}

/// Get a human-readable, translated name of the combination
/// of GUI environment and style. E.g. "plasma:dark" becomes "Plasma (Dark)".
/// ## `env_style`
/// a GUI environment style ID, e.g. "pantheon:dark"
///
/// # Returns
///
/// A localized name of the environment style, or [`None`] if none available.
#[doc(alias = "as_utils_get_gui_environment_style_name")]
pub fn utils_get_gui_environment_style_name(env_style: &str) -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe {
        from_glib_none(ffi::as_utils_get_gui_environment_style_name(
            env_style.to_glib_none().0,
        ))
    }
}

/// Retrieve the raw search token weight for the given tag name that AppStream uses
/// internally for searching.
/// This can be used to implement separate, but compatible search logic.
/// ## `tag_name`
/// A tag name in a component element, e.g. "name" or "summary" or "keyword"
///
/// # Returns
///
/// The tag weight used in (fulltext) searches. 0 for lowest weight/unused.
#[doc(alias = "as_utils_get_tag_search_weight")]
pub fn utils_get_tag_search_weight(tag_name: &str) -> u16 {
    assert_initialized_main_thread!();
    unsafe { ffi::as_utils_get_tag_search_weight(tag_name.to_glib_none().0) }
}

/// Guess the [`ComponentScope`][crate::ComponentScope] that applies to a given path.
/// ## `path`
/// The filename to test.
///
/// # Returns
///
/// the [`ComponentScope`][crate::ComponentScope]
#[doc(alias = "as_utils_guess_scope_from_path")]
pub fn utils_guess_scope_from_path(path: &str) -> ComponentScope {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::as_utils_guess_scope_from_path(path.to_glib_none().0)) }
}

/// 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.
/// ## `location`
/// the [`MetadataLocation`][crate::MetadataLocation], e.g. [`MetadataLocation::Cache`][crate::MetadataLocation::Cache]
/// ## `filename`
/// the full path of the file to install
/// ## `origin`
/// the origin to use for the installation, or [`None`]
/// ## `destdir`
/// the destdir to use, or [`None`]
///
/// # Returns
///
/// [`true`] for success, [`false`] if error is set
#[doc(alias = "as_utils_install_metadata_file")]
pub fn utils_install_metadata_file(
    location: MetadataLocation,
    filename: &str,
    origin: &str,
    destdir: &str,
) -> Result<(), glib::Error> {
    assert_initialized_main_thread!();
    unsafe {
        let mut error = std::ptr::null_mut();
        let is_ok = ffi::as_utils_install_metadata_file(
            location.into_glib(),
            filename.to_glib_none().0,
            origin.to_glib_none().0,
            destdir.to_glib_none().0,
            &mut error,
        );
        debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
        if error.is_null() {
            Ok(())
        } else {
            Err(from_glib_full(error))
        }
    }
}

#[doc(alias = "as_utils_is_category_name")]
pub fn utils_is_category_name(category_name: &str) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::as_utils_is_category_name(
            category_name.to_glib_none().0,
        ))
    }
}

/// Checks if the submitted desktop environment ID is
/// known and valid.
/// ## `de_id`
/// a desktop environment id.
///
/// # Returns
///
/// [`true`] if the desktop-id is valid
#[doc(alias = "as_utils_is_desktop_environment")]
pub fn utils_is_desktop_environment(de_id: &str) -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::as_utils_is_desktop_environment(de_id.to_glib_none().0)) }
}

/// Checks if the given identifier is a valid, known GUI environment style.
/// ## `env_style`
/// a GUI environment style ID, e.g. "pantheon:dark"
///
/// # Returns
///
/// [`true`] if the environment-style ID is is valid
#[doc(alias = "as_utils_is_gui_environment_style")]
pub fn utils_is_gui_environment_style(env_style: &str) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::as_utils_is_gui_environment_style(
            env_style.to_glib_none().0,
        ))
    }
}

/// Test if the given string is a valid platform triplet recognized by
/// AppStream.
/// ## `triplet`
/// a platform triplet.
///
/// # Returns
///
/// [`true`] if triplet is valid.
#[doc(alias = "as_utils_is_platform_triplet")]
pub fn utils_is_platform_triplet(triplet: &str) -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::as_utils_is_platform_triplet(triplet.to_glib_none().0)) }
}

/// Searches the known list of TLDs we allow for AppStream IDs.
/// This excludes internationalized names.
/// ## `tld`
/// a top-level domain without dot, e.g. "de", "org", "name"
///
/// # Returns
///
/// [`true`] if the TLD is valid
#[doc(alias = "as_utils_is_tld")]
pub fn utils_is_tld(tld: &str) -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::as_utils_is_tld(tld.to_glib_none().0)) }
}

/// Calculates if one locale is compatible with another.
/// When doing the calculation the locale and language code is taken into
/// account if possible.
/// ## `locale1`
/// a BCP47 or POSIX locale string, or [`None`]
/// ## `locale2`
/// a BCP47 or POSIX locale string, or [`None`]
///
/// # Returns
///
/// [`true`] if the locale is compatible.
#[doc(alias = "as_utils_locale_is_compatible")]
pub fn utils_locale_is_compatible(locale1: Option<&str>, locale2: Option<&str>) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::as_utils_locale_is_compatible(
            locale1.to_glib_none().0,
            locale2.to_glib_none().0,
        ))
    }
}

/// Converts a POSIX locale string to the corresponding IETF BCP47 format.
/// If the given locale is already in BCP47 format, no change will be done.
///
/// # Returns
///
/// A locale string, free with `g_free()`
#[doc(alias = "as_utils_posix_locale_to_bcp47")]
pub fn utils_posix_locale_to_bcp47(locale: &str) -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe { from_glib_full(ffi::as_utils_posix_locale_to_bcp47(locale.to_glib_none().0)) }
}

/// Sorts all components in `cpts` into the [`Category`][crate::Category] categories listed in `categories`.
/// ## `cpts`
/// List of components.
/// ## `categories`
/// List of categories to sort components into.
/// ## `check_duplicates`
/// Whether to check for duplicates.
#[doc(alias = "as_utils_sort_components_into_categories")]
pub fn utils_sort_components_into_categories(
    cpts: &[Component],
    categories: &[Category],
    check_duplicates: bool,
) {
    assert_initialized_main_thread!();
    unsafe {
        ffi::as_utils_sort_components_into_categories(
            cpts.to_glib_none().0,
            categories.to_glib_none().0,
            check_duplicates.into_glib(),
        );
    }
}

/// Compare alpha and numeric segments of two software versions,
/// considering `flags`.
/// ## `a`
/// First version number
/// ## `b`
/// Second version number
/// ## `flags`
/// Flags, e.g. [`VercmpFlags::NONE`][crate::VercmpFlags::NONE]
///
/// # Returns
///
/// >>0 if a is newer than b;
///  0 if a and b are the same version;
///  <<0 if b is newer than a
#[doc(alias = "as_vercmp")]
pub fn vercmp(a: &str, b: &str, flags: VercmpFlags) -> i32 {
    assert_initialized_main_thread!();
    unsafe { ffi::as_vercmp(a.to_glib_none().0, b.to_glib_none().0, flags.into_glib()) }
}

/// Compare alpha and numeric segments of two software versions.
/// ## `a`
/// First version number
/// ## `b`
/// Second version number
///
/// # Returns
///
/// >>0 if a is newer than b;
///  0 if a and b are the same version;
///  <<0 if b is newer than a
#[doc(alias = "as_vercmp_simple")]
pub fn vercmp_simple(a: &str, b: &str) -> i32 {
    assert_initialized_main_thread!();
    unsafe { ffi::as_vercmp_simple(a.to_glib_none().0, b.to_glib_none().0) }
}

/// Compare two version numbers and check if the given version comparator matches.
/// ## `ver1`
/// first version number
/// ## `compare`
/// the comparison operator
/// ## `ver2`
/// second version number
/// ## `flags`
/// the [`VercmpFlags`][crate::VercmpFlags] to use
///
/// # Returns
///
/// [`true`] if the version comparison matches, [`false`] otherwise.
#[doc(alias = "as_vercmp_test_match")]
pub fn vercmp_test_match(
    ver1: &str,
    compare: RelationCompare,
    ver2: &str,
    flags: VercmpFlags,
) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::as_vercmp_test_match(
            ver1.to_glib_none().0,
            compare.into_glib(),
            ver2.to_glib_none().0,
            flags.into_glib(),
        ))
    }
}

/// Get the version of the AppStream library that is currently used
/// at runtime as a string.
///
/// # Returns
///
/// a version number, e.g. "0.14.2"
#[doc(alias = "as_version_string")]
pub fn version_string() -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe { from_glib_none(ffi::as_version_string()) }
}