AsComponent: AppStream Library Reference Manual

## AsComponent AsComponent — Object representing a software component |

## Functions

const gchar * | as_component_kind_to_string ()
AsComponentKind | as_component_kind_from_string ()
AsComponent * | as_component_new ()
gboolean | as_component_is_valid ()
gchar * | as_component_to_string ()
gchar * | as_component_get_active_locale ()
void | as_component_set_active_locale ()
AsComponentKind | as_component_get_kind ()
void | as_component_set_kind ()
const gchar * | as_component_get_id ()
void | as_component_set_id ()
const gchar * | as_component_get_origin ()
void | as_component_set_origin ()
gchar ** | as_component_get_pkgnames ()
void | as_component_set_pkgnames ()
const gchar * | as_component_get_source_pkgname ()
void | as_component_set_source_pkgname ()
const gchar * | as_component_get_name ()
void | as_component_set_name ()
const gchar * | as_component_get_summary ()
void | as_component_set_summary ()
const gchar * | as_component_get_description ()
void | as_component_set_description ()
const gchar * | as_component_get_project_license ()
void | as_component_set_project_license ()
const gchar * | as_component_get_project_group ()
void | as_component_set_project_group ()
const gchar * | as_component_get_developer_name ()
void | as_component_set_developer_name ()
gchar ** | as_component_get_compulsory_for_desktops ()
void | as_component_set_compulsory_for_desktops ()
gboolean | as_component_is_compulsory_for_desktop ()
gchar ** | as_component_get_categories ()
void | as_component_set_categories ()
gboolean | as_component_has_category ()
GPtrArray * | as_component_get_screenshots ()
void | as_component_add_screenshot ()
gchar ** | as_component_get_keywords ()
void | as_component_set_keywords ()
GPtrArray * | as_component_get_icons ()
AsIcon * | as_component_get_icon_by_size ()
void | as_component_add_icon ()
void | as_component_add_provided ()
AsProvided * | as_component_get_provided_for_kind ()
GList * | as_component_get_provided ()
const gchar * | as_component_get_url ()
void | as_component_add_url ()
GPtrArray * | as_component_get_releases ()
void | as_component_add_release ()
GPtrArray * | as_component_get_extends ()
void | as_component_add_extends ()
GPtrArray * | as_component_get_extensions ()
void | as_component_add_extension ()
GList * | as_component_get_languages ()
gint | as_component_get_language ()
void | as_component_add_language ()
GPtrArray * | as_component_get_translations ()
void | as_component_add_translation ()
gboolean | as_component_has_bundle ()
const gchar * | as_component_get_bundle_id ()
void | as_component_add_bundle_id ()
GPtrArray * | as_component_get_search_tokens ()
guint | as_component_search_matches ()

## Properties

GStrv | categories | Read / Write
gchar * | description | Read / Write
gchar * | developer-name | Read / Write
gpointer | icons | Read
gchar * | id | Read / Write
GStrv | keywords | Read / Write
AsComponentKind | kind | Read / Write
gchar * | name | Read / Write
GStrv | pkgnames | Read / Write
gchar * | project-group | Read / Write
gchar * | project-license | Read / Write
GPtrArray * | screenshots | Read
gchar * | summary | Read / Write
GHashTable * | urls | Read

## Types and Values

#define | AS_TYPE_COMPONENT
struct | AsComponentClass
enum | AsComponentKind
| AsComponent

## Object Hierarchy

        GEnum
        ╰── AsComponentKind
        GObject
        ╰── AsComponent

## Includes

    #include <appstream.h>

## Description

This object represents an Appstream software component which is associated to a package in the distribution's repositories. A component can be anything, ranging from an application to a font, a codec or even a non-visual software project providing libraries and python-modules for other applications to use.

The type of the component is stored as AsComponentKind and can be queried to find out which kind of component we're dealing with.

See also: AsProvidesKind, AsDatabase

## Functions

### as_component_kind_to_string ()

    const gchar *
    as_component_kind_to_string (AsComponentKind kind);

Converts the enumerated value to an text representation.

#### Parameters

kind | the `AsComponentKind`. |

#### Returns

string version of `kind`

### as_component_kind_from_string ()

    AsComponentKind
    as_component_kind_from_string (const gchar *kind_str);

Converts the text representation to an enumerated value.

#### Parameters

kind_str | the string. |

#### Returns

a AsComponentKind or `AS_COMPONENT_KIND_UNKNOWN` for unknown

### as_component_new ()

    AsComponent *
    as_component_new (void);

Creates a new AsComponent.

#### Returns

a new AsComponent.

[transfer full]

### as_component_is_valid ()

    gboolean
    as_component_is_valid (AsComponent *cpt);

Check if the essential properties of this Component are populated with useful data.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

TRUE if the component data was validated successfully.

### as_component_to_string ()

    gchar *
    as_component_to_string (AsComponent *cpt);

Returns a string identifying this component. (useful for debugging)

#### Parameters

cpt | a AsComponent instance. |

#### Returns

A descriptive string.

[transfer full]

### as_component_get_active_locale ()

    gchar *
    as_component_get_active_locale (AsComponent *cpt);

Get the current active locale for this component, which is used to get localized messages.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

the current active locale.

### as_component_set_active_locale ()

    void
    as_component_set_active_locale (AsComponent *cpt,
                                    const gchar *locale);

Set the current active locale for this component, which is used to get localized messages. If the AsComponent was fetched from a localized database, usually only one locale is available.

#### Parameters

cpt | a AsComponent instance. |
locale | the locale, or `NULL`. e.g. "en_GB". | [nullable]

### as_component_get_kind ()

    AsComponentKind
    as_component_get_kind (AsComponent *cpt);

Returns the AsComponentKind of this component.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

the kind of this.

### as_component_set_kind ()

    void
    as_component_set_kind (AsComponent *cpt,
                           AsComponentKind value);

Sets the AsComponentKind of this component.

#### Parameters

cpt | a AsComponent instance. |
value | the AsComponentKind. |

### as_component_get_id ()

    const gchar *
    as_component_get_id (AsComponent *cpt);

Get the unique identifier for this component.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

the unique identifier.

### as_component_set_id ()

    void
    as_component_set_id (AsComponent *cpt,
                         const gchar *value);

Set the unique identifier for this component.

#### Parameters

cpt | a AsComponent instance. |
value | the unique identifier. |

### as_component_get_origin ()

    const gchar *
    as_component_get_origin (AsComponent *cpt);

#### Parameters

cpt | a AsComponent instance. |

### as_component_set_origin ()

    void
    as_component_set_origin (AsComponent *cpt,
                             const gchar *origin);

#### Parameters

cpt | a AsComponent instance. |
origin | the origin. |

### as_component_get_pkgnames ()

    gchar **
    as_component_get_pkgnames (AsComponent *cpt);

Get a list of package names which this component consists of. This usually is just one package name.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

String array of package names.

[transfer none]

### as_component_set_pkgnames ()

    void
    as_component_set_pkgnames (AsComponent *cpt,
                               gchar **value);

Set a list of package names this component consists of. (This should usually be just one package name)

#### Parameters

cpt | a AsComponent instance. |
value | . | [array zero-terminated=1]

### as_component_get_source_pkgname ()

    const gchar *
    as_component_get_source_pkgname (AsComponent *cpt);

#### Parameters

cpt | a AsComponent instance. |

#### Returns

the source package name.

### as_component_set_source_pkgname ()

    void
    as_component_set_source_pkgname (AsComponent *cpt,
                                     const gchar *spkgname);

#### Parameters

cpt | a AsComponent instance. |
spkgname | the source package name. |

### as_component_get_name ()

    const gchar *
    as_component_get_name (AsComponent *cpt);

A human-readable name for this component.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

the name.

### as_component_set_name ()

    void
    as_component_set_name (AsComponent *cpt,
                           const gchar *value,
                           const gchar *locale);

Set a human-readable name for this component.

#### Parameters

cpt | A valid AsComponent |
value | The name |
locale | The locale the used for this value, or `NULL` to use the current active one. | [nullable]

### as_component_get_summary ()

    const gchar *
    as_component_get_summary (AsComponent *cpt);

Get a short description of this component.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

the summary.

### as_component_set_summary ()

    void
    as_component_set_summary (AsComponent *cpt,
                              const gchar *value,
                              const gchar *locale);

Set a short description for this component.

#### Parameters

cpt | A valid AsComponent |
value | The summary |
locale | The locale the used for this value, or `NULL` to use the current active one. | [nullable]

### as_component_get_description ()

    const gchar *
    as_component_get_description (AsComponent *cpt);

Get the localized long description of this component.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

the description.

### as_component_set_description ()

    void
    as_component_set_description (AsComponent *cpt,
                                  const gchar *value,
                                  const gchar *locale);

Set long description for this component.

#### Parameters

cpt | A valid AsComponent |
value | The long description |
locale | The locale the used for this value, or `NULL` to use the current active one. | [nullable]

### as_component_get_project_license ()

    const gchar *
    as_component_get_project_license (AsComponent *cpt);

Get the license of the project this component belongs to.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

the license.

### as_component_set_project_license ()

    void
    as_component_set_project_license (AsComponent *cpt,
                                      const gchar *value);

Set the project license.

#### Parameters

cpt | a AsComponent instance. |
value | the project license. |

### as_component_get_project_group ()

    const gchar *
    as_component_get_project_group (AsComponent *cpt);

Get the component's project group.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

the project group.

### as_component_set_project_group ()

    void
    as_component_set_project_group (AsComponent *cpt,
                                    const gchar *value);

Set the component's project group.

#### Parameters

cpt | a AsComponent instance. |
value | the project group. |

### as_component_get_developer_name ()

    const gchar *
    as_component_get_developer_name (AsComponent *cpt);

Get the component's developer or development team name.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

the developer name.

### as_component_set_developer_name ()

    void
    as_component_set_developer_name (AsComponent *cpt,
                                     const gchar *value,
                                     const gchar *locale);

Set the the component's developer or development team name.

#### Parameters

cpt | a AsComponent instance. |
value | the developer or developer team name |
locale | the locale, or `NULL`. e.g. "en_GB". | [nullable]

### as_component_get_compulsory_for_desktops ()

    gchar **
    as_component_get_compulsory_for_desktops
                                   (AsComponent *cpt);

#### Parameters

cpt | a AsComponent instance. |

#### Returns

A list of desktops where this component is compulsory.

[transfer none]

### as_component_set_compulsory_for_desktops ()

    void
    as_component_set_compulsory_for_desktops
                                   (AsComponent *cpt,
                                    gchar **value);

Set a list of desktops where this component is compulsory.

#### Parameters

cpt | a AsComponent instance. |
value | the array of desktop ids. | [array zero-terminated=1]

### as_component_is_compulsory_for_desktop ()

    gboolean
    as_component_is_compulsory_for_desktop
                                   (AsComponent *cpt,
                                    const gchar *desktop);

Check if this component is compulsory for the given desktop.

#### Parameters

cpt | an AsComponent object |
desktop | the desktop-id to test for |

#### Returns

`TRUE` if compulsory, `FALSE` otherwise.

### as_component_get_categories ()

    gchar **
    as_component_get_categories (AsComponent *cpt);

#### Parameters

cpt | a AsComponent instance. |

#### Returns

String array of categories.

[transfer none]

### as_component_set_categories ()

    void
    as_component_set_categories (AsComponent *cpt,
                                 gchar **value);

#### Parameters

cpt | a AsComponent instance. |
value | the categories name. | [array zero-terminated=1]

### as_component_has_category ()

    gboolean
    as_component_has_category (AsComponent *cpt,
                               const gchar *category);

Check if component is in the specified category.

#### Parameters

cpt | an AsComponent object |
category | the specified category to check |

#### Returns

`TRUE` if the component is in the specified category.

### as_component_get_screenshots ()

    GPtrArray *
    as_component_get_screenshots (AsComponent *cpt);

Get a list of associated screenshots.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

an array of AsScreenshot instances.

[element-type AsScreenshot][transfer none]

### as_component_add_screenshot ()

    void
    as_component_add_screenshot (AsComponent *cpt,
                                 AsScreenshot *sshot);

Add an AsScreenshot to this component.

#### Parameters

cpt | a AsComponent instance. |
sshot | The AsScreenshot to add |

### as_component_get_keywords ()

    gchar **
    as_component_get_keywords (AsComponent *cpt);

#### Parameters

cpt | a AsComponent instance. |

#### Returns

String array of keywords.

[transfer none]

### as_component_set_keywords ()

    void
    as_component_set_keywords (AsComponent *cpt,
                               gchar **value,
                               const gchar *locale);

Set keywords for this component.

#### Parameters

cpt | a AsComponent instance. |
value | String-array of keywords. | [array zero-terminated=1]
locale | Locale of the values, or `NULL` to use current locale. | [nullable]

### as_component_get_icons ()

    GPtrArray *
    as_component_get_icons (AsComponent *cpt);

#### Parameters

cpt | an AsComponent instance |

#### Returns

A GPtrArray of all icons for this component.

[element-type AsIcon][transfer none]

### as_component_get_icon_by_size ()

    AsIcon *
    as_component_get_icon_by_size (AsComponent *cpt,
                                   guint width,
                                   guint height);

Gets an icon matching the size constraints. The icons are not filtered by type, and the first icon which matches the size is returned. If you want more control over which icons you use for displaying, use the `as_component_get_icons()` function to get a list of all icons.

#### Parameters

cpt | an AsComponent instance |
width | The icon width in pixels. |
height | the icon height in pixels. |

#### Returns

An icon matching the given width/height, or `NULL` if not found.

[transfer none]

### as_component_add_icon ()

    void
    as_component_add_icon (AsComponent *cpt,
                           AsIcon *icon);

Add an icon to this component.

#### Parameters

cpt | an AsComponent instance |
icon | the valid AsIcon instance to add. |

### as_component_add_provided ()

    void
    as_component_add_provided (AsComponent *cpt,
                               AsProvided *prov);

Add a set of provided items to this component.

#### Parameters

cpt | a AsComponent instance. |
prov | a AsProvided instance. |

Since: 0.6.2

### as_component_get_provided_for_kind ()

    AsProvided *
    as_component_get_provided_for_kind (AsComponent *cpt,
                                        AsProvidedKind kind);

Get an AsProvided object for the given interface type, containing information about the public interfaces (mimetypes, firmware, DBus services, ...) this component provides.

#### Parameters

cpt | a AsComponent instance. |
kind | kind of the provided item, e.g. `AS_PROVIDED_KIND_MIMETYPE` |

#### Returns

AsProvided containing the items this component provides, or `NULL`.

[transfer none]

### as_component_get_provided ()

    GList *
    as_component_get_provided (AsComponent *cpt);

Get a list of AsProvided objects associated with this component.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

A list of AsProvided objects.

[transfer container][element-type AsProvided]

### as_component_get_url ()

    const gchar *
    as_component_get_url (AsComponent *cpt,
                          AsUrlKind url_kind);

Gets a URL.

#### Parameters

cpt | a AsComponent instance. |
url_kind | the URL kind, e.g. `AS_URL_KIND_HOMEPAGE`. |

#### Returns

string, or `NULL` if unset.

[nullable]

Since: 0.6.2

### as_component_add_url ()

    void
    as_component_add_url (AsComponent *cpt,
                          AsUrlKind url_kind,
                          const gchar *url);

Adds some URL data to the component.

#### Parameters

cpt | a AsComponent instance. |
url_kind | the URL kind, e.g. `AS_URL_KIND_HOMEPAGE` |
url | the full URL. |

Since: 0.6.2

### as_component_get_releases ()

    GPtrArray *
    as_component_get_releases (AsComponent *cpt);

Get an array of the AsRelease items this component provides.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

A list of releases.

[element-type AsRelease][transfer none]

### as_component_add_release ()

    void
    as_component_add_release (AsComponent *cpt,
                              AsRelease *release);

Add an AsRelease to this component.

#### Parameters

cpt | a AsComponent instance. |
release | The AsRelease to add |

### as_component_get_extends ()

    GPtrArray *
    as_component_get_extends (AsComponent *cpt);

Returns a string list of IDs of components which are extended by this addon.

See `as_component_get_extends`() for the reverse.

#### Parameters

cpt | an AsComponent instance. |

#### Returns

A GPtrArray or `NULL` if not set.

[element-type utf8][transfer none]

Since: 0.7.0

### as_component_add_extends ()

    void
    as_component_add_extends (AsComponent *cpt,
                              const gchar *cpt_id);

Add a reference to the extended component

#### Parameters

cpt | a AsComponent instance. |
cpt_id | The id of a component which is extended by this component |

Since: 0.7.0

### as_component_get_extensions ()

    GPtrArray *
    as_component_get_extensions (AsComponent *cpt);

Returns a string list of IDs of components which are addons extending this component in functionality.

This is the reverse of `as_component_get_extends`()

#### Parameters

cpt | an AsComponent instance. |

#### Returns

A GPtrArray or `NULL` if not set.

[element-type utf8][transfer none]

Since: 0.9.2

### as_component_add_extension ()

    void
    as_component_add_extension (AsComponent *cpt,
                                const gchar *cpt_id);

Add a reference to the extension enhancing this component.

#### Parameters

cpt | a AsComponent instance. |
cpt_id | The id of a component extending this component. |

Since: 0.9.2

### as_component_get_languages ()

    GList *
    as_component_get_languages (AsComponent *cpt);

Get a list of all languages.

#### Parameters

cpt | an AsComponent instance. |

#### Returns

list of locales.

[transfer container][element-type utf8]

Since: 0.7.0

### as_component_get_language ()

    gint
    as_component_get_language (AsComponent *cpt,
                               const gchar *locale);

Gets the translation coverage in percent for a specific locale

#### Parameters

cpt | an AsComponent instance. |
locale | the locale, or `NULL`. e.g. "en_GB". | [nullable]

#### Returns

a percentage value, -1 if locale was not found

Since: 0.7.0

### as_component_add_language ()

    void
    as_component_add_language (AsComponent *cpt,
                               const gchar *locale,
                               gint percentage);

Adds a language to the component.

#### Parameters

cpt | an AsComponent instance. |
locale | the locale, or `NULL`. e.g. "en_GB". | [nullable]
percentage | the percentage completion of the translation, 0 for locales with unknown amount of translation |

Since: 0.7.0

### as_component_get_translations ()

    GPtrArray *
    as_component_get_translations (AsComponent *cpt);

Get a GPtrArray of AsTranslation objects describing the translation systems and translation-ids (e.g. Gettext domains) used by this software component.

Only set for metainfo files.

#### Parameters

cpt | an AsComponent instance. |

#### Returns

An array of AsTranslation objects.

[transfer none][element-type AsTranslation]

Since: 0.9.2

### as_component_add_translation ()

    void
    as_component_add_translation (AsComponent *cpt,
                                  AsTranslation *tr);

Assign an AsTranslation object describing the translation system used by this component.

#### Parameters

cpt | an AsComponent instance. |
tr | an AsTranslation instance. |

Since: 0.9.2

### as_component_has_bundle ()

    gboolean
    as_component_has_bundle (AsComponent *cpt);

#### Parameters

cpt | a AsComponent instance. |

#### Returns

`TRUE` if this component has a bundle-id associated.

### as_component_get_bundle_id ()

    const gchar *
    as_component_get_bundle_id (AsComponent *cpt,
                                AsBundleKind bundle_kind);

Gets a bundle identifier string.

#### Parameters

cpt | a AsComponent instance. |
bundle_kind | the bundle kind, e.g. `AS_BUNDLE_KIND_LIMBA`. |

#### Returns

string, or `NULL` if unset.

[nullable]

Since: 0.8.0

### as_component_add_bundle_id ()

    void
    as_component_add_bundle_id (AsComponent *cpt,
                                AsBundleKind bundle_kind,
                                const gchar *id);

Adds a bundle identifier to the component.

#### Parameters

cpt | a AsComponent instance. |
bundle_kind | the URL kind, e.g. `AS_BUNDLE_KIND_LIMBA` |
id | The bundle identification string |

Since: 0.8.0

### as_component_get_search_tokens ()

    GPtrArray *
    as_component_get_search_tokens (AsComponent *cpt);

Returns all search tokens for this component.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

The string search tokens.

[transfer full][element-type utf8]

Since: 0.9.7

### as_component_search_matches ()

    guint
    as_component_search_matches (AsComponent *cpt,
                                 const gchar *search_term);

Searches component data for a specific keyword.

#### Parameters

cpt | a AsComponent instance. |
search_term | the search term. |

#### Returns

a match scrore, where 0 is no match and 100 is the best match.

Since: 0.9.7

## Types and Values

### AS_TYPE_COMPONENT

    #define AS_TYPE_COMPONENT (as_component_get_type ())

### struct AsComponentClass

    struct AsComponentClass {
    	GObjectClass		parent_class;
    };

### enum AsComponentKind

The type of an AsComponent.

#### Members

AS_COMPONENT_KIND_UNKNOWN | Type invalid or not known |
AS_COMPONENT_KIND_GENERIC | A generic (= without specialized type) component |
AS_COMPONENT_KIND_DESKTOP_APP | An application with a .desktop-file |
AS_COMPONENT_KIND_FONT | A font |
AS_COMPONENT_KIND_CODEC | A multimedia codec |
AS_COMPONENT_KIND_INPUTMETHOD | An input-method provider |
AS_COMPONENT_KIND_ADDON | An extension of existing software, which does not run standalone |
AS_COMPONENT_KIND_FIRMWARE | Firmware |

### AsComponent

    typedef struct _AsComponent AsComponent;

## Property Details

### The `“categories”` property

      “categories”               GStrv

string array of categories

Flags: Read / Write

### The `“description”` property

      “description”              gchar *

the description

Flags: Read / Write

Default value: NULL

### The `“developer-name”` property

      “developer-name”           gchar *

the developer name

Flags: Read / Write

Default value: NULL

### The `“icons”` property

      “icons”                    gpointer

hash map of icon urls and sizes

[type GList(AsIcon)]

Flags: Read

### The `“id”` property

      “id”                       gchar *

the unique identifier

Flags: Read / Write

Default value: NULL

### The `“keywords”` property

      “keywords”                 GStrv

string array of keywords

Flags: Read / Write

### The `“kind”` property

      “kind”                     AsComponentKind

the AsComponentKind of this component

Flags: Read / Write

Default value: AS_COMPONENT_KIND_UNKNOWN

### The `“name”` property

      “name”                     gchar *

the name

Flags: Read / Write

Default value: NULL

### The `“pkgnames”` property

      “pkgnames”                 GStrv

string array of packages name

Flags: Read / Write

### The `“project-group”` property

      “project-group”            gchar *

the project group

Flags: Read / Write

Default value: NULL

### The `“project-license”` property

      “project-license”          gchar *

the project license

Flags: Read / Write

Default value: NULL

### The `“screenshots”` property

      “screenshots”              GPtrArray *

screenshots.

Flags: Read

### The `“summary”` property

      “summary”                  gchar *

the summary

Flags: Read / Write

Default value: NULL

### The `“urls”` property

      “urls”                     GHashTable *

urls.

Flags: Read