AsMetadata

AsMetadata — Parser for AppStream metadata

Functions

Types and Values

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_format_kind_to_string ()

const gchar *
as_format_kind_to_string (AsFormatKind kind);

Converts the enumerated value to an text representation.

Parameters

kind

the AsFormatKind.

 

Returns

string version of kind

Since: 0.10


as_format_kind_from_string ()

AsFormatKind
as_format_kind_from_string (const gchar *kind_str);

Converts the text representation to an enumerated value.

Parameters

kind_str

the string.

 

Returns

a AsFormatKind or AS_FORMAT_KIND_UNKNOWN for unknown

Since: 0.10


as_format_version_to_string ()

const gchar *
as_format_version_to_string (AsFormatVersion version);

Converts the enumerated value to an text representation.

Parameters

version

the AsFormatKind.

 

Returns

string version of version

Since: 0.10


as_format_version_from_string ()

AsFormatVersion
as_format_version_from_string (const gchar *version_str);

Converts the text representation to an enumerated value.

Parameters

version_str

the string.

 

Returns

a AsFormatVersion. For unknown, the highest version number is assumed.

Since: 0.10


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,
                        AsFormatKind format,
                        GError **error);

Parses an AppStream upstream metadata file.

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.

 

as_metadata_parse ()

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

Parses AppStream metadata.

Parameters

metad

An instance of AsMetadata.

 

data

Metadata describing one or more software components.

 

format

The format of the data (XML or YAML).

 

error

A GError or NULL.

 

as_metadata_parse_desktop_data ()

void
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 pool.

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.

 

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

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

 

as_metadata_components_to_collection ()

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

Serialize all AsComponent instances into AppStream collection 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_collection ()

void
as_metadata_save_collection (AsMetadata *metad,
                             const gchar *fname,
                             AsFormatKind format,
                             GError **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 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 collection 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 collection 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_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.

 

Types and Values

AS_TYPE_METADATA

#define AS_TYPE_METADATA (as_metadata_get_type ())

struct AsMetadataClass

struct AsMetadataClass {
	GObjectClass		parent_class;
};

enum AsFormatStyle

There are a few differences between AppStream's metainfo files (shipped by upstream projects) and the collection metadata (shipped by distributors). The data source kind indicates which style we should process. Usually you do not want to set this explicitly.

Members

AS_FORMAT_STYLE_UNKNOWN

   

AS_FORMAT_STYLE_METAINFO

Parse AppStream upstream metadata (metainfo files)

 

AS_FORMAT_STYLE_COLLECTION

Parse AppStream metadata collections (shipped by software distributors)

 

enum AsFormatKind

Format of the AppStream metadata.

Members

AS_FORMAT_KIND_UNKNOWN

Unknown metadata format.

 

AS_FORMAT_KIND_XML

AppStream XML metadata.

 

AS_FORMAT_KIND_YAML

AppStream YAML (DEP-11) metadata.

 

AS_FORMAT_KIND_DESKTOP_ENTRY

XDG Desktop Entry data.

 

enum AsFormatVersion

Format version / API level of the AppStream metadata.

Members

AS_FORMAT_VERSION_V0_6

0.6

 

AS_FORMAT_VERSION_V0_7

0.7

 

AS_FORMAT_VERSION_V0_8

0.8

 

AS_FORMAT_VERSION_V0_9

0.9

 

AS_FORMAT_VERSION_V0_10

0.10

 

AS_FORMAT_VERSION_V0_11

0.11

 

AS_FORMAT_VERSION_V0_12

0.12

 

AS_CURRENT_FORMAT_VERSION

#define AS_CURRENT_FORMAT_VERSION AS_FORMAT_VERSION_V0_12

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 collection 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;