## AsMetadata

AsMetadata — Parser for AppStream metadata

## Functions

AsFormatStyle | as_metadata_file_guess_style ()
AsMetadata * | as_metadata_new ()
GQuark | as_metadata_error_quark ()
gboolean | as_metadata_parse_file ()
gboolean | as_metadata_parse ()
gboolean | as_metadata_parse_bytes ()
gboolean | as_metadata_parse_desktop_data ()
GPtrArray * | as_metadata_parse_releases_bytes ()
GPtrArray * | as_metadata_parse_releases_file ()
gchar * | as_metadata_releases_to_data ()
AsComponent * | as_metadata_get_component ()
GPtrArray * | as_metadata_get_components ()
void | as_metadata_clear_components ()
void | as_metadata_add_component ()
gchar * | as_metadata_component_to_metainfo ()
gboolean | as_metadata_save_metainfo ()
gchar * | as_metadata_components_to_catalog ()
gboolean | as_metadata_save_catalog ()
AsFormatVersion | as_metadata_get_format_version ()
void | as_metadata_set_format_version ()
AsFormatStyle | as_metadata_get_format_style ()
void | as_metadata_set_format_style ()
void | as_metadata_set_locale ()
const gchar * | as_metadata_get_locale ()
const gchar * | as_metadata_get_origin ()
void | as_metadata_set_origin ()
gboolean | as_metadata_get_update_existing ()
void | as_metadata_set_update_existing ()
gboolean | as_metadata_get_write_header ()
void | as_metadata_set_write_header ()
const gchar * | as_metadata_get_media_baseurl ()
void | as_metadata_set_media_baseurl ()
const gchar * | as_metadata_get_architecture ()
void | as_metadata_set_architecture ()
AsParseFlags | as_metadata_get_parse_flags ()
void | as_metadata_set_parse_flags ()
gchar * | as_metadata_components_to_collection ()
gboolean | as_metadata_save_collection ()

## Types and Values

#define | AS_TYPE_METADATA
struct | AsMetadataClass
enum | AsParseFlags
enum | AsMetadataError
#define | AS_METADATA_ERROR
| AsMetadata

## Includes

    #include <appstream.h>

## Description

This object parses AppStream metadata, including AppStream upstream metadata, which is defined by upstream projects. It returns an AsComponent of the data.

See also: AsComponent, AsDatabase

## Functions

### as_metadata_file_guess_style ()

    AsFormatStyle
    as_metadata_file_guess_style (const gchar *filename);

Guesses the AppStream metadata style (metainfo or catalog) based on the filename.

#### Parameters

filename | a file name |

#### Returns

An AsFormatStyle, e.g. `AS_FORMAT_STYLE_METAINFO`.

Since: 0.14.0

### as_metadata_new ()

    AsMetadata *
    as_metadata_new (void);

Creates a new AsMetadata.

#### Returns

a AsMetadata.

[transfer full]

### as_metadata_error_quark ()

    GQuark
    as_metadata_error_quark (void);

#### Returns

An error quark.

### as_metadata_parse_file ()

    gboolean
    as_metadata_parse_file (AsMetadata *metad,
                            GFile *file,
                            AsFormatKind format,
                            GError **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.

#### Parameters

metad | A valid AsMetadata instance |
file | GFile for the upstream metadata |
format | The format the data is in, or `AS_FORMAT_KIND_UNKNOWN` if not known. |
error | A GError or `NULL`. |

#### Returns

`TRUE` if the file was parsed without error.

### as_metadata_parse ()

    gboolean
    as_metadata_parse (AsMetadata *metad,
                       const gchar *data,
                       AsFormatKind format,
                       GError **error);

Parses any AppStream metadata into one or more AsComponent instances.

#### Parameters

metad | An instance of AsMetadata. |
data | Metadata describing one or more software components as null-terminated string. |
format | The format of the data (XML or YAML). |
error | A GError or `NULL`. |

#### Returns

`TRUE` on success.

### as_metadata_parse_bytes ()

    gboolean
    as_metadata_parse_bytes (AsMetadata *metad,
                             GBytes *bytes,
                             AsFormatKind format,
                             GError **error);

Parses any AppStream metadata into one or more AsComponent instances.

#### Parameters

metad | An instance of AsMetadata. |
bytes | Metadata describing one or more software components. |
format | The format of the data (XML or YAML). |
error | A GError or `NULL`. |

#### Returns

`TRUE` on success.

Since: 0.14.0

### as_metadata_parse_desktop_data ()

    gboolean
    as_metadata_parse_desktop_data (AsMetadata *metad,
                                    const gchar *data,
                                    const gchar *cid,
                                    GError **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).

#### Parameters

metad | An instance of AsMetadata. |
data | Metadata describing one or more software components. |
cid | The component-id the new AsComponent should have. |
error | A GError or `NULL`. |

#### Returns

`TRUE` if the file was parsed without error.

### as_metadata_parse_releases_bytes ()

    GPtrArray *
    as_metadata_parse_releases_bytes (AsMetadata *metad,
                                      GBytes *bytes,
                                      GError **error);

Parses any AppStream release metadata into AsRelease objects.

#### Parameters

metad | An instance of AsMetadata. |
bytes | Metadata describing release notes. |
error | A GError or `NULL`. |

#### Returns

A list of releases or `NULL` on error.

[element-type AsRelease][transfer container][nullable]

Since: 0.16.0

### as_metadata_parse_releases_file ()

    GPtrArray *
    as_metadata_parse_releases_file (AsMetadata *metad,
                                     GFile *file,
                                     GError **error);

Parses any AppStream release metadata into AsRelease objects using the provided file.

#### Parameters

metad | A valid AsMetadata instance |
file | GFile for the release metadata |
error | A GError or `NULL`. |

#### Returns

A list of releases or `NULL` on error.

[element-type AsRelease][transfer container][nullable]

Since: 0.16.0

### as_metadata_releases_to_data ()

    gchar *
    as_metadata_releases_to_data (AsMetadata *metad,
                                  GPtrArray *releases,
                                  GError **error);

Convert a list of Asrelease entities into a release metadata XML representation.

#### Parameters

metad | A valid AsMetadata instance |
releases | the list of Asrelease to convert. | [element-type AsRelease]
error | A GError or `NULL`. |

#### Returns

The XML representation or `NULL` on error.

Since: 0.16.0

### as_metadata_get_component ()

    AsComponent *
    as_metadata_get_component (AsMetadata *metad);

Gets the AsComponent which has been parsed from the XML. If the AppStream XML contained multiple components, return the first component that has been parsed.

#### Parameters

metad | a AsMetadata instance. |

#### Returns

An AsComponent or `NULL`.

[transfer none][nullable]

### as_metadata_get_components ()

    GPtrArray *
    as_metadata_get_components (AsMetadata *metad);

#### Parameters

metad | a AsMetadata instance. |

#### Returns

A GPtrArray of all parsed components.

[transfer none][element-type AsComponent]

### as_metadata_clear_components ()

    void
    as_metadata_clear_components (AsMetadata *metad);

### as_metadata_add_component ()

    void
    as_metadata_add_component (AsMetadata *metad,
                               AsComponent *cpt);

Add an AsComponent to the list of components. This can be used to add multiple components in order to produce a distro-XML AppStream metadata file.

### as_metadata_component_to_metainfo ()

    gchar *
    as_metadata_component_to_metainfo (AsMetadata *metad,
                                       AsFormatKind format,
                                       GError **error);

Convert an AsComponent 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 AsComponent was initially loaded and whether it contains data for all locale.

The first AsComponent added to the internal list will be transformed. In case no component is present, `NULL` is returned.

#### Parameters

metad | An instance of AsMetadata. |
format | The format to use (XML or YAML) |
error | A GError |

#### Returns

A string containing the XML metadata. Free with `g_free()`.

[transfer full]

### as_metadata_save_metainfo ()

    gboolean
    as_metadata_save_metainfo (AsMetadata *metad,
                               const gchar *fname,
                               AsFormatKind format,
                               GError **error);

Serialize AsComponent instance to XML and save it to file. An existing file at the same location will be overridden.

#### Parameters

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.

### as_metadata_components_to_catalog ()

    gchar *
    as_metadata_components_to_catalog (AsMetadata *metad,
                                       AsFormatKind format,
                                       GError **error);

Serialize all AsComponent instances into AppStream catalog metadata. `NULL` is returned if there is nothing to serialize.

#### Parameters

metad | An instance of AsMetadata. |
format | The format to serialize the data to (XML or YAML). |
error | A GError |

#### Returns

A string containing the YAML or XML data. Free with `g_free()`.

[transfer full]

### as_metadata_save_catalog ()

    gboolean
    as_metadata_save_catalog (AsMetadata *metad,
                              const gchar *fname,
                              AsFormatKind format,
                              GError **error);

Serialize all AsComponent instances to XML or YAML metadata and save the data to a file. An existing file at the same location will be overridden.

#### Parameters

metad | An instance of AsMetadata. |
fname | The filename for the new metadata file. |

#### Returns

`TRUE` if the file was written without error.

### as_metadata_get_format_version ()

    AsFormatVersion
    as_metadata_get_format_version (AsMetadata *metad);

#### Parameters

metad | an AsMetadata instance. |

#### Returns

The AppStream metadata format version.

### as_metadata_set_format_version ()

    void
    as_metadata_set_format_version (AsMetadata *metad,
                                    AsFormatVersion version);

Set the current AppStream format version that we should generate data for or be able to read.

#### Parameters

metad | a AsMetadata instance. |
version | the AppStream metadata format version as AsFormatVersion. |

### as_metadata_get_format_style ()

    AsFormatStyle
    as_metadata_get_format_style (AsMetadata *metad);

Get the metadata parsing mode.

#### Parameters

metad | a AsMetadata instance. |

### as_metadata_set_format_style ()

    void
    as_metadata_set_format_style (AsMetadata *metad,
                                  AsFormatStyle mode);

Sets the current metadata parsing mode.

#### Parameters

metad | a AsMetadata instance. |
mode | the AsFormatStyle. |

### as_metadata_set_locale ()

    void
    as_metadata_set_locale (AsMetadata *metad,
                            const gchar *locale);

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.

#### Parameters

metad | a AsMetadata instance. |
locale | the BCP47 locale. |

### as_metadata_get_locale ()

    const gchar *
    as_metadata_get_locale (AsMetadata *metad);

Gets the current active locale for parsing metadata, or "ALL" if all locales are read.

#### Parameters

metad | a AsMetadata instance. |

#### Returns

Locale used for metadata parsing.

### as_metadata_get_origin ()

    const gchar *
    as_metadata_get_origin (AsMetadata *metad);

#### Parameters

metad | an AsMetadata instance. |

#### Returns

The origin of AppStream distro metadata

### as_metadata_set_origin ()

    void
    as_metadata_set_origin (AsMetadata *metad,
                            const gchar *origin);

Set the origin of AppStream distro metadata

#### Parameters

metad | an AsMetadata instance. |
origin | the origin of AppStream distro metadata. |

### as_metadata_get_update_existing ()

    gboolean
    as_metadata_get_update_existing (AsMetadata *metad);

#### Parameters

metad | an AsMetadata instance. |

#### Returns

Whether existing components should be updates with the parsed data, instead of creating new ones.

### as_metadata_set_update_existing ()

    void
    as_metadata_set_update_existing (AsMetadata *metad,
                                     gboolean update);

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!

#### Parameters

metad | an AsMetadata instance. |
update | A boolean value. |

### as_metadata_get_write_header ()

    gboolean
    as_metadata_get_write_header (AsMetadata *metad);

#### Parameters

metad | an AsMetadata instance. |

#### Returns

Whether we will write a header/root node in catalog metadata.

### as_metadata_set_write_header ()

    void
    as_metadata_set_write_header (AsMetadata *metad,
                                  gboolean wheader);

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!

#### Parameters

metad | an AsMetadata instance. |
wheader | A boolean value. |

### as_metadata_get_media_baseurl ()

    const gchar *
    as_metadata_get_media_baseurl (AsMetadata *metad);

#### Parameters

metad | an AsMetadata instance. |

#### Returns

The media URL prefix.

### as_metadata_set_media_baseurl ()

    void
    as_metadata_set_media_baseurl (AsMetadata *metad,
                                   const gchar *url);

Set the base URL for all media links referenced in the metadata, or `NULL` if every component has absolute URLs.

#### Parameters

metad | an AsMetadata instance. |
url | the base URL. |

### as_metadata_get_architecture ()

    const gchar *
    as_metadata_get_architecture (AsMetadata *metad);

#### Parameters

metad | an AsMetadata instance. |

#### Returns

The architecture of AppStream distro metadata

### as_metadata_set_architecture ()

    void
    as_metadata_set_architecture (AsMetadata *metad,
                                  const gchar *arch);

Set the architecture the components in this metadata belong to.

#### Parameters

metad | an AsMetadata instance. |
arch | an architecture string. |

### as_metadata_get_parse_flags ()

    AsParseFlags
    as_metadata_get_parse_flags (AsMetadata *metad);

Get the metadata parse flags.

#### Parameters

metad | a AsMetadata instance. |

### as_metadata_set_parse_flags ()

    void
    as_metadata_set_parse_flags (AsMetadata *metad,
                                 AsParseFlags flags);

Sets the current metadata parse flags.

#### Parameters

metad | a AsMetadata instance. |
flags | the AsParseFlags. |

### as_metadata_components_to_collection ()

    gchar *
    as_metadata_components_to_collection (AsMetadata *metad,
                                          AsFormatKind format,
                                          GError **error);

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

Deprecated, use `as_metadata_components_to_catalog` instead.

#### Parameters

metad | An instance of AsMetadata. |
format | The format to serialize the data to (XML or YAML). |
error | A GError |

#### Returns

A string containing the YAML or XML data. Free with `g_free()`.

[transfer full]

### as_metadata_save_collection ()

    gboolean
    as_metadata_save_collection (AsMetadata *metad,
                                 const gchar *fname,
                                 AsFormatKind format,
                                 GError **error);

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

Deprecated, use `as_metadata_save_catalog` instead.

#### Parameters

metad | An instance of AsMetadata. |
fname | The filename for the new metadata file. |

#### Returns

`TRUE` if the file was written without error.

## Types and Values

### AS_TYPE_METADATA

    #define AS_TYPE_METADATA (as_metadata_get_type ())

### struct AsMetadataClass

    struct AsMetadataClass {
    	GObjectClass		parent_class;
    };

### enum AsParseFlags

Influence certain aspects of how AppStream metadata is parsed.

#### Members

AS_PARSE_FLAG_NONE | No flags. |
AS_PARSE_FLAG_IGNORE_MEDIABASEURL | Do not process the media_baseurl document property. |

### enum AsMetadataError

A metadata processing error.

#### Members

AS_METADATA_ERROR_FAILED | Generic failure. |
AS_METADATA_ERROR_PARSE | Unable to parse the metadata file. |
AS_METADATA_ERROR_FORMAT_UNEXPECTED | Expected catalog metadata but got metainfo metadata, or vice versa. |
AS_METADATA_ERROR_NO_COMPONENT | We expected a component in the pool, but couldn't find one. |
AS_METADATA_ERROR_VALUE_MISSING | A essential value is missing in the source document. |

### AS_METADATA_ERROR

    #define AS_METADATA_ERROR as_metadata_error_quark ()

### AsMetadata

    typedef struct _AsMetadata AsMetadata;