libappstream/auto/

metadata.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, Component, ComponentBox, FormatKind, FormatStyle, FormatVersion, ParseFlags, ReleaseList,
};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    ///
    ///
    /// # Implements
    ///
    /// [`MetadataExt`][trait@crate::prelude::MetadataExt]
    #[doc(alias = "AsMetadata")]
    pub struct Metadata(Object<ffi::AsMetadata, ffi::AsMetadataClass>);

    match fn {
        type_ => || ffi::as_metadata_get_type(),
    }
}

impl Metadata {
    pub const NONE: Option<&'static Metadata> = None;

    /// Creates a new [`Metadata`][crate::Metadata].
    ///
    /// # Returns
    ///
    /// a [`Metadata`][crate::Metadata]
    #[doc(alias = "as_metadata_new")]
    pub fn new() -> Metadata {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::as_metadata_new()) }
    }

    /// Guesses the AppStream metadata style (metainfo or catalog) based on
    /// the filename.
    /// ## `filename`
    /// a file name
    ///
    /// # Returns
    ///
    /// An [`FormatStyle`][crate::FormatStyle], e.g. [`FormatStyle::Metainfo`][crate::FormatStyle::Metainfo].
    #[doc(alias = "as_metadata_file_guess_style")]
    pub fn file_guess_style(filename: &str) -> FormatStyle {
        assert_initialized_main_thread!();
        unsafe { from_glib(ffi::as_metadata_file_guess_style(filename.to_glib_none().0)) }
    }
}

impl Default for Metadata {
    fn default() -> Self {
        Self::new()
    }
}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::Metadata>> Sealed for T {}
}

/// Trait containing all [`struct@Metadata`] methods.
///
/// # Implementors
///
/// [`Metadata`][struct@crate::Metadata]
pub trait MetadataExt: IsA<Metadata> + sealed::Sealed + 'static {
    /// Add an [`Component`][crate::Component] to the list of components.
    /// This can be used to add multiple components in order to
    /// produce a distro-XML AppStream metadata file.
    #[doc(alias = "as_metadata_add_component")]
    fn add_component(&self, cpt: &impl IsA<Component>) {
        unsafe {
            ffi::as_metadata_add_component(
                self.as_ref().to_glib_none().0,
                cpt.as_ref().to_glib_none().0,
            );
        }
    }

    /// Remove all previously parsed or manually added components.
    #[doc(alias = "as_metadata_clear_components")]
    fn clear_components(&self) {
        unsafe {
            ffi::as_metadata_clear_components(self.as_ref().to_glib_none().0);
        }
    }

    /// Remove all previously parsed releases entries.
    #[doc(alias = "as_metadata_clear_releases")]
    fn clear_releases(&self) {
        unsafe {
            ffi::as_metadata_clear_releases(self.as_ref().to_glib_none().0);
        }
    }

    /// Convert an [`Component`][crate::Component] to metainfo data.
    /// This will always be XML, YAML is no valid format for metainfo files.
    ///
    /// The amount of localization included in the metadata depends on how the [`Component`][crate::Component]
    /// was initially loaded and whether it contains data for all locale.
    ///
    /// The first [`Component`][crate::Component] added to the internal list will be transformed.
    /// In case no component is present, [`None`] is returned.
    /// ## `format`
    /// The format to use (XML or YAML)
    ///
    /// # Returns
    ///
    /// A string containing the XML metadata. Free with `g_free()`
    #[doc(alias = "as_metadata_component_to_metainfo")]
    fn component_to_metainfo(&self, format: FormatKind) -> Result<glib::GString, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::as_metadata_component_to_metainfo(
                self.as_ref().to_glib_none().0,
                format.into_glib(),
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Serialize all [`Component`][crate::Component] instances into AppStream
    /// catalog metadata.
    /// [`None`] is returned if there is nothing to serialize.
    /// ## `format`
    /// The format to serialize the data to (XML or YAML).
    ///
    /// # Returns
    ///
    /// A string containing the YAML or XML data. Free with `g_free()`
    #[doc(alias = "as_metadata_components_to_catalog")]
    fn components_to_catalog(&self, format: FormatKind) -> Result<glib::GString, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::as_metadata_components_to_catalog(
                self.as_ref().to_glib_none().0,
                format.into_glib(),
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    ///
    /// # Returns
    ///
    /// The architecture of AppStream distro metadata
    #[doc(alias = "as_metadata_get_architecture")]
    #[doc(alias = "get_architecture")]
    fn architecture(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::as_metadata_get_architecture(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the [`Component`][crate::Component] which has been parsed from the XML.
    /// If the AppStream XML contained multiple components, return the last
    /// component that has been parsed.
    ///
    /// # Returns
    ///
    /// An [`Component`][crate::Component] or [`None`]
    #[doc(alias = "as_metadata_get_component")]
    #[doc(alias = "get_component")]
    fn component(&self) -> Option<Component> {
        unsafe {
            from_glib_none(ffi::as_metadata_get_component(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    ///
    /// # Returns
    ///
    /// an [`ComponentBox`][crate::ComponentBox] of all parsed components
    #[doc(alias = "as_metadata_get_components")]
    #[doc(alias = "get_components")]
    fn components(&self) -> Option<ComponentBox> {
        unsafe {
            from_glib_none(ffi::as_metadata_get_components(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Get the metadata parsing mode.
    #[doc(alias = "as_metadata_get_format_style")]
    #[doc(alias = "get_format_style")]
    fn format_style(&self) -> FormatStyle {
        unsafe {
            from_glib(ffi::as_metadata_get_format_style(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    ///
    /// # Returns
    ///
    /// The AppStream metadata format version.
    #[doc(alias = "as_metadata_get_format_version")]
    #[doc(alias = "get_format_version")]
    fn format_version(&self) -> FormatVersion {
        unsafe {
            from_glib(ffi::as_metadata_get_format_version(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the current active locale for parsing metadata,
    /// or "ALL" if all locales are read.
    ///
    /// # Returns
    ///
    /// Locale used for metadata parsing.
    #[doc(alias = "as_metadata_get_locale")]
    #[doc(alias = "get_locale")]
    fn locale(&self) -> Option<glib::GString> {
        unsafe { from_glib_none(ffi::as_metadata_get_locale(self.as_ref().to_glib_none().0)) }
    }

    ///
    /// # Returns
    ///
    /// The media URL prefix.
    #[doc(alias = "as_metadata_get_media_baseurl")]
    #[doc(alias = "get_media_baseurl")]
    fn media_baseurl(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::as_metadata_get_media_baseurl(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    ///
    /// # Returns
    ///
    /// The origin of AppStream distro metadata
    #[doc(alias = "as_metadata_get_origin")]
    #[doc(alias = "get_origin")]
    fn origin(&self) -> Option<glib::GString> {
        unsafe { from_glib_none(ffi::as_metadata_get_origin(self.as_ref().to_glib_none().0)) }
    }

    /// Get the metadata parse flags.
    #[doc(alias = "as_metadata_get_parse_flags")]
    #[doc(alias = "get_parse_flags")]
    fn parse_flags(&self) -> ParseFlags {
        unsafe {
            from_glib(ffi::as_metadata_get_parse_flags(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the recently parsed [`ReleaseList`][crate::ReleaseList] entry.
    ///
    /// # Returns
    ///
    /// An [`ReleaseList`][crate::ReleaseList] or [`None`]
    #[doc(alias = "as_metadata_get_release_list")]
    #[doc(alias = "get_release_list")]
    fn release_list(&self) -> Option<ReleaseList> {
        unsafe {
            from_glib_none(ffi::as_metadata_get_release_list(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    ///
    /// # Returns
    ///
    /// A `GPtrArray` of all parsed release metadata.
    #[doc(alias = "as_metadata_get_release_lists")]
    #[doc(alias = "get_release_lists")]
    fn release_lists(&self) -> Vec<ReleaseList> {
        unsafe {
            FromGlibPtrContainer::from_glib_none(ffi::as_metadata_get_release_lists(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    ///
    /// # Returns
    ///
    /// Whether existing components should be updates with the parsed data,
    ///  instead of creating new ones.
    #[doc(alias = "as_metadata_get_update_existing")]
    #[doc(alias = "get_update_existing")]
    fn is_update_existing(&self) -> bool {
        unsafe {
            from_glib(ffi::as_metadata_get_update_existing(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    ///
    /// # Returns
    ///
    /// Whether we will write a header/root node in catalog metadata.
    #[doc(alias = "as_metadata_get_write_header")]
    #[doc(alias = "get_write_header")]
    fn is_write_header(&self) -> bool {
        unsafe {
            from_glib(ffi::as_metadata_get_write_header(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Parses any AppStream metadata into one or more [`Component`][crate::Component] instances.
    /// ## `bytes`
    /// Metadata describing one or more software components.
    /// ## `format`
    /// The format of the data (XML or YAML).
    ///
    /// # Returns
    ///
    /// [`true`] on success.
    #[doc(alias = "as_metadata_parse_bytes")]
    fn parse_bytes(&self, bytes: &glib::Bytes, format: FormatKind) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::as_metadata_parse_bytes(
                self.as_ref().to_glib_none().0,
                bytes.to_glib_none().0,
                format.into_glib(),
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Parses any AppStream metadata into one or more [`Component`][crate::Component] instances.
    /// ## `data`
    /// Metadata describing one or more software components as string.
    /// ## `data_len`
    /// Length of `data`, or -1 if length is unknown and `data` is NULL-terminated.
    /// ## `format`
    /// The format of the data (XML or YAML).
    ///
    /// # Returns
    ///
    /// [`true`] on success.
    #[doc(alias = "as_metadata_parse_data")]
    fn parse_data(&self, data: &str, format: FormatKind) -> Result<(), glib::Error> {
        let data_len = data.len() as _;
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::as_metadata_parse_data(
                self.as_ref().to_glib_none().0,
                data.to_glib_none().0,
                data_len,
                format.into_glib(),
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Parses XDG Desktop Entry metadata and adds it to the list of parsed entities.
    ///
    /// Please note that not every desktop-entry file will result in a valid component
    /// being generated, even if parsing succeeds without error (The desktiop-entry file
    /// may be valid but not generate a component on purpose).
    /// ## `cid`
    /// The component-id the new [`Component`][crate::Component] should have.
    /// ## `data`
    /// Metadata describing one or more software components.
    /// ## `data_len`
    /// The data length, or -1 if unknown and null-terminated.
    ///
    /// # Returns
    ///
    /// [`true`] if the file was parsed without error.
    #[doc(alias = "as_metadata_parse_desktop_data")]
    fn parse_desktop_data(&self, cid: &str, data: &str) -> Result<(), glib::Error> {
        let data_len = data.len() as _;
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::as_metadata_parse_desktop_data(
                self.as_ref().to_glib_none().0,
                cid.to_glib_none().0,
                data.to_glib_none().0,
                data_len,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Parses an AppStream upstream metadata file.
    ///
    /// If `file` does not exist, `G_IO_ERROR_NOT_FOUND` will be returned. Other
    /// `GIOErrors` and `AsMetadataErrors` may be returned as appropriate.
    /// ## `file`
    /// [`gio::File`][crate::gio::File] for the upstream metadata
    /// ## `format`
    /// The format the data is in, or [`FormatKind::Unknown`][crate::FormatKind::Unknown] if not known.
    ///
    /// # Returns
    ///
    /// [`true`] if the file was parsed without error.
    #[doc(alias = "as_metadata_parse_file")]
    fn parse_file(
        &self,
        file: &impl IsA<gio::File>,
        format: FormatKind,
    ) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::as_metadata_parse_file(
                self.as_ref().to_glib_none().0,
                file.as_ref().to_glib_none().0,
                format.into_glib(),
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Parses any AppStream release metadata into [`Release`][crate::Release] objects.
    /// You can retrieve the last parsed [`ReleaseList`][crate::ReleaseList] using `as_metadata_get_release_list`.
    /// ## `bytes`
    /// Metadata describing release notes.
    ///
    /// # Returns
    ///
    /// [`true`] on success.
    #[doc(alias = "as_metadata_parse_releases_bytes")]
    fn parse_releases_bytes(&self, bytes: &glib::Bytes) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::as_metadata_parse_releases_bytes(
                self.as_ref().to_glib_none().0,
                bytes.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))
            }
        }
    }

    /// Parses any AppStream release metadata into [`Release`][crate::Release] objects
    /// using the provided file.
    /// You can retrieve the last parsed [`ReleaseList`][crate::ReleaseList] using `as_metadata_get_release_list`.
    /// ## `file`
    /// [`gio::File`][crate::gio::File] for the release metadata
    ///
    /// # Returns
    ///
    /// [`true`] on success.
    #[doc(alias = "as_metadata_parse_releases_file")]
    fn parse_releases_file(&self, file: &impl IsA<gio::File>) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::as_metadata_parse_releases_file(
                self.as_ref().to_glib_none().0,
                file.as_ref().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))
            }
        }
    }

    /// Convert a releases of an [`ReleaseList`][crate::ReleaseList] entity into a release metadata XML representation.
    /// ## `releases`
    /// the [`ReleaseList`][crate::ReleaseList] to convert.
    ///
    /// # Returns
    ///
    /// The XML representation or [`None`] on error.
    #[doc(alias = "as_metadata_releases_to_data")]
    fn releases_to_data(
        &self,
        releases: &impl IsA<ReleaseList>,
    ) -> Result<glib::GString, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::as_metadata_releases_to_data(
                self.as_ref().to_glib_none().0,
                releases.as_ref().to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Serialize all [`Component`][crate::Component] instances to XML or YAML metadata and save
    /// the data to a file.
    /// An existing file at the same location will be overridden.
    /// ## `fname`
    /// The filename for the new metadata file.
    ///
    /// # Returns
    ///
    /// [`true`] if the file was written without error.
    #[doc(alias = "as_metadata_save_catalog")]
    fn save_catalog(&self, fname: &str, format: FormatKind) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::as_metadata_save_catalog(
                self.as_ref().to_glib_none().0,
                fname.to_glib_none().0,
                format.into_glib(),
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Serialize [`Component`][crate::Component] instance to XML and save it to file.
    /// An existing file at the same location will be overridden.
    /// ## `fname`
    /// The filename for the new metadata file.
    /// ## `format`
    /// The format to save this file in. Only XML is supported at time.
    ///
    /// # Returns
    ///
    /// [`true`] if the file was written without error.
    #[doc(alias = "as_metadata_save_metainfo")]
    fn save_metainfo(&self, fname: &str, format: FormatKind) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::as_metadata_save_metainfo(
                self.as_ref().to_glib_none().0,
                fname.to_glib_none().0,
                format.into_glib(),
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Set the architecture the components in this metadata belong to.
    /// ## `arch`
    /// an architecture string.
    #[doc(alias = "as_metadata_set_architecture")]
    fn set_architecture(&self, arch: &str) {
        unsafe {
            ffi::as_metadata_set_architecture(
                self.as_ref().to_glib_none().0,
                arch.to_glib_none().0,
            );
        }
    }

    /// Sets the current metadata parsing mode.
    /// ## `mode`
    /// the [`FormatStyle`][crate::FormatStyle].
    #[doc(alias = "as_metadata_set_format_style")]
    fn set_format_style(&self, mode: FormatStyle) {
        unsafe {
            ffi::as_metadata_set_format_style(self.as_ref().to_glib_none().0, mode.into_glib());
        }
    }

    /// Set the current AppStream format version that we should generate data for
    /// or be able to read.
    /// ## `version`
    /// the AppStream metadata format version as [`FormatVersion`][crate::FormatVersion].
    #[doc(alias = "as_metadata_set_format_version")]
    fn set_format_version(&self, version: FormatVersion) {
        unsafe {
            ffi::as_metadata_set_format_version(
                self.as_ref().to_glib_none().0,
                version.into_glib(),
            );
        }
    }

    /// Sets the locale which should be read when processing metadata.
    /// All other locales are ignored, which increases parsing speed and
    /// reduces memory usage.
    /// If you set the locale to "ALL", all locales will be read.
    /// ## `locale`
    /// the BCP47 locale.
    #[doc(alias = "as_metadata_set_locale")]
    fn set_locale(&self, locale: &str) {
        unsafe {
            ffi::as_metadata_set_locale(self.as_ref().to_glib_none().0, locale.to_glib_none().0);
        }
    }

    /// Set the base URL for all media links referenced in the metadata,
    /// or [`None`] if every component has absolute URLs.
    /// ## `url`
    /// the base URL.
    #[doc(alias = "as_metadata_set_media_baseurl")]
    fn set_media_baseurl(&self, url: &str) {
        unsafe {
            ffi::as_metadata_set_media_baseurl(
                self.as_ref().to_glib_none().0,
                url.to_glib_none().0,
            );
        }
    }

    /// Set the origin of AppStream distro metadata
    /// ## `origin`
    /// the origin of AppStream distro metadata.
    #[doc(alias = "as_metadata_set_origin")]
    fn set_origin(&self, origin: &str) {
        unsafe {
            ffi::as_metadata_set_origin(self.as_ref().to_glib_none().0, origin.to_glib_none().0);
        }
    }

    /// Sets the current metadata parse flags.
    /// ## `flags`
    /// the [`ParseFlags`][crate::ParseFlags].
    #[doc(alias = "as_metadata_set_parse_flags")]
    fn set_parse_flags(&self, flags: ParseFlags) {
        unsafe {
            ffi::as_metadata_set_parse_flags(self.as_ref().to_glib_none().0, flags.into_glib());
        }
    }

    /// If set to [`true`], the parser will not create new components but
    /// instead update existing components in the pool with new metadata.
    ///
    /// NOTE: Right now, this feature is only implemented for metainfo XML parsing!
    /// ## `update`
    /// A boolean value.
    #[doc(alias = "as_metadata_set_update_existing")]
    fn set_update_existing(&self, update: bool) {
        unsafe {
            ffi::as_metadata_set_update_existing(
                self.as_ref().to_glib_none().0,
                update.into_glib(),
            );
        }
    }

    /// If set to [`true`], tehe metadata writer will omit writing a DEP-11
    /// header document when in YAML mode, and will not write a root components node
    /// when writing XML data.
    /// Please keep in mind that this will create an invalid DEP-11 YAML AppStream
    /// catalog metadata file, and an invalid XML file.
    /// This parameter should only be changed e.g. by the appstream-generator tool.
    ///
    /// NOTE: Right now, this feature is only implemented for YAML!
    /// ## `wheader`
    /// A boolean value.
    #[doc(alias = "as_metadata_set_write_header")]
    fn set_write_header(&self, wheader: bool) {
        unsafe {
            ffi::as_metadata_set_write_header(self.as_ref().to_glib_none().0, wheader.into_glib());
        }
    }
}

impl<O: IsA<Metadata>> MetadataExt for O {}