AsMetadata: AppStream Library Reference Manual

## AsMetadata AsMetadata — Parser for AppStream metadata |

## Functions

AsMetadata * | as_metadata_new ()
GQuark | as_metadata_error_quark ()
void | as_metadata_parse_file ()
void | as_metadata_parse_xml ()
void | as_metadata_parse_yaml ()
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_upstream_xml ()
void | as_metadata_save_upstream_xml ()
gchar * | as_metadata_components_to_distro_xml ()
void | as_metadata_save_distro_xml ()
gchar * | as_metadata_components_to_distro_yaml ()
void | as_metadata_save_distro_yaml ()
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 ()
void | as_metadata_set_parser_mode ()
AsParserMode | as_metadata_get_parser_mode ()
const gchar * | as_metadata_get_architecture ()
void | as_metadata_set_architecture ()

## Types and Values

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

## Object Hierarchy

        GObject
        ╰── 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_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 ()

    void
    as_metadata_parse_file (AsMetadata *metad,
                            GFile *file,
                            GError **error);

Parses an AppStream upstream metadata file.

#### Parameters

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

### as_metadata_parse_xml ()

    void
    as_metadata_parse_xml (AsMetadata *metad,
                           const gchar *data,
                           GError **error);

Parses AppStream XML metadata.

#### Parameters

metad | A valid AsMetadata instance |
data | XML data describing one or more software components. |

### as_metadata_parse_yaml ()

    void
    as_metadata_parse_yaml (AsMetadata *metad,
                            const gchar *data,
                            GError **error);

Parses AppStream YAML metadata.

#### Parameters

metad | A valid AsMetadata instance |
data | YAML data describing one or more software components. |
error | A GError or `NULL`. |

### 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]

### 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_upstream_xml ()

    gchar *
    as_metadata_component_to_upstream_xml (AsMetadata *metad);

Convert an AsComponent to upstream XML. (The amount of localization included in the metadata depends on how the AsComponent was initially loaded)

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

#### Returns

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

[transfer full]

### as_metadata_save_upstream_xml ()

    void
    as_metadata_save_upstream_xml (AsMetadata *metad,
                                   const gchar *fname,
                                   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 XML file. |

### as_metadata_components_to_distro_xml ()

    gchar *
    as_metadata_components_to_distro_xml (AsMetadata *metad);

Serialize all AsComponent instances into AppStream distro-XML data. `NULL` is returned if there is nothing to serialize.

#### Returns

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

[transfer full]

### as_metadata_save_distro_xml ()

    void
    as_metadata_save_distro_xml (AsMetadata *metad,
                                 const gchar *fname,
                                 GError **error);

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

#### Parameters

fname | The filename for the new XML file. |

### as_metadata_components_to_distro_yaml ()

    gchar *
    as_metadata_components_to_distro_yaml (AsMetadata *metad);

Serialize all AsComponent instances into AppStream DEP-11 distro-YAML data. `NULL` is returned if there is nothing to serialize.

#### Returns

A string containing the YAML markup. Free with `g_free()`.

[transfer full]

### as_metadata_save_distro_yaml ()

    void
    as_metadata_save_distro_yaml (AsMetadata *metad,
                                  const gchar *fname,
                                  GError **error);

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

#### Parameters

fname | The filename for the new YAML file. |

### 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 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 distro 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 distro 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_set_parser_mode ()

    void
    as_metadata_set_parser_mode (AsMetadata *metad,
                                 AsParserMode mode);

Sets the current metadata parsing mode.

#### Parameters

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

### as_metadata_get_parser_mode ()

    AsParserMode
    as_metadata_get_parser_mode (AsMetadata *metad);

Gets the current parser mode

#### Parameters

metad | a AsMetadata instance. |

#### Returns

an AsParserMode

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

## Types and Values

### AS_TYPE_METADATA

    #define AS_TYPE_METADATA (as_metadata_get_type ())

### struct AsMetadataClass

    struct AsMetadataClass {
    	GObjectClass		parent_class;
    };

### enum AsParserMode

There are a few differences between Appstream's upstream metadata and the distribution metadata. The parser mode indicates which style we should process. Usually you don't want to change this.

#### Members

AS_PARSER_MODE_UPSTREAM | Parse Appstream upstream metadata |
AS_PARSER_MODE_DISTRO | Parse Appstream distribution metadata |

### 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_UNEXPECTED_FORMAT_KIND | Expected upstream metadata but got distro metadata, or vice versa. |
AS_METADATA_ERROR_NO_COMPONENT | We expected a component in the pool, but couldn't find one. |

### AS_METADATA_ERROR

    #define AS_METADATA_ERROR as_metadata_error_quark ()

### AsMetadata

    typedef struct _AsMetadata AsMetadata;