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 ()
AsIconKind | as_icon_kind_from_string ()
const gchar * | as_icon_kind_to_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 ()
void | as_component_set_categories_from_str ()
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 ()
const gchar * | as_component_get_icon ()
void | as_component_add_icon ()
const gchar * | as_component_get_icon_url ()
void | as_component_add_icon_url ()
GHashTable * | as_component_get_icon_urls ()
GPtrArray * | as_component_get_provided_items ()
void | as_component_add_provided_item ()
gboolean | as_component_provides_item ()
GHashTable * | as_component_get_urls ()
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 ()
void | as_component_add_language ()
gint | as_component_get_language ()
GList * | as_component_get_languages ()
GHashTable * | as_component_get_bundle_ids ()
const gchar * | as_component_get_bundle_id ()
void | as_component_add_bundle_id ()

## Properties

GStrv | categories | Read / Write
gchar * | description | Read / Write
gchar * | developer-name | Read / Write
GHashTable * | icon-urls | 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

enum | AsComponentKind
enum | AsIconKind

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

    AsIconKind
    as_icon_kind_from_string (const gchar *kind_str);

Converts the text representation to an enumerated value.

#### Parameters

kind_str | the string. |

#### Returns

a AsIconKind or `AS_ICON_KIND_UNKNOWN` for unknown

### as_icon_kind_to_string ()

    const gchar *
    as_icon_kind_to_string (AsIconKind kind);

Converts the enumerated value to an text representation.

#### Parameters

kind | the `AsIconKind`. |

#### Returns

string version of `kind`

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

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

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

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

### as_component_get_kind ()

    AsComponentKind
    as_component_get_kind (AsComponent *cpt);

Returns the AsComponentKind of this component.

### as_component_set_kind ()

    void
    as_component_set_kind (AsComponent *cpt,
                           AsComponentKind value);

Sets the AsComponentKind of this component.

### as_component_get_id ()

    const gchar *
    as_component_get_id (AsComponent *cpt);

Set the unique identifier for this component.

### as_component_set_id ()

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

Set the unique identifier for this component.

### as_component_get_origin ()

    const gchar *
    as_component_get_origin (AsComponent *cpt);

### as_component_set_origin ()

    void
    as_component_set_origin (AsComponent *cpt,
                             const gchar *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.

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

value | . | [array zero-terminated=1]

### as_component_get_source_pkgname ()

    const gchar *
    as_component_get_source_pkgname (AsComponent *cpt);

### as_component_set_source_pkgname ()

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

### as_component_get_name ()

    const gchar *
    as_component_get_name (AsComponent *cpt);

A human-readable name for this component.

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

### as_component_get_summary ()

    const gchar *
    as_component_get_summary (AsComponent *cpt);

Get a short description of this component.

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

### as_component_get_description ()

    const gchar *
    as_component_get_description (AsComponent *cpt);

Get the localized long description of this component.

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

### as_component_get_project_license ()

    const gchar *
    as_component_get_project_license (AsComponent *cpt);

Get the license of the project this component belongs to.

### as_component_set_project_license ()

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

Set the project license.

### as_component_get_project_group ()

    const gchar *
    as_component_get_project_group (AsComponent *cpt);

Get the component's project group.

### as_component_set_project_group ()

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

Set the component's 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.

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

### as_component_get_compulsory_for_desktops ()

    gchar **
    as_component_get_compulsory_for_desktops
                                   (AsComponent *cpt);

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

### 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);

#### Returns

String array of categories.

[transfer none]

### as_component_set_categories ()

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

#### Parameters

value | . | [array zero-terminated=1]

### as_component_set_categories_from_str ()

    void
    as_component_set_categories_from_str (AsComponent *cpt,
                                          const gchar *categories_str);

Set the categories list from a string

#### Parameters

cpt | a valid AsComponent instance |
categories_str | Semicolon-separated list of category-names |

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

### as_component_get_screenshots ()

    GPtrArray *
    as_component_get_screenshots (AsComponent *cpt);

Get a list of associated screenshots.

#### 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);

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

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

### as_component_get_icon ()

    const gchar *
    as_component_get_icon (AsComponent *cpt,
                           AsIconKind kind,
                           int width,
                           int height);

#### Parameters

cpt | an AsComponent instance |

#### Returns

The raw icon data found for the given icon kind and size. If the icon kind is `AS_ICON_KIND_STOCK`, the size is ignored. `NULL` is returned in case no icon was found.

### as_component_add_icon ()

    void
    as_component_add_icon (AsComponent *cpt,
                           AsIconKind kind,
                           int width,
                           int height,
                           const gchar *value);

Add an icon of the given type to this component.

#### Parameters

cpt | an AsComponent instance |

### as_component_get_icon_url ()

    const gchar *
    as_component_get_icon_url (AsComponent *cpt,
                               int width,
                               int height);

A convenience method to retrieve an icon for this component. This method is designed to be used by software center applications, it will always return a full path or url to a valid icon, in contrast to the `as_component_get_icon()` method, which returns unprocessed icon data.

#### Parameters

cpt | an AsComponent instance |
width | An icon width |
height | An icon height |

#### Returns

The full url for an icon with the given width and height. In case no icon matching the size is found, `NULL` is returned. The returned path will either be a http link or an absolute, local path to the image file of the icon.

Since: 0.7.4

### as_component_add_icon_url ()

    void
    as_component_add_icon_url (AsComponent *cpt,
                               int width,
                               int height,
                               const gchar *value);

Set an icon url for this component, which can be a remote or local location.

The icon_url does not end up in XML generated for this component, it is mereley designed to be a fast way to get icon information for a component. If you want to set an icon which gets serialized to AppStream xml, use the `as_component_add_icon()` method instead.

#### Parameters

cpt | an AsComponent instance |
width | An icon width |
height | An icon height |
value | The full icon url |

Since: 0.7.4

### as_component_get_icon_urls ()

    GHashTable *
    as_component_get_icon_urls (AsComponent *cpt);

Gets the icon-urls has table for the component.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

A hash map of icon urls and sizes.

[transfer none]

Since: 0.7.4

### as_component_get_provided_items ()

    GPtrArray *
    as_component_get_provided_items (AsComponent *cpt);

Get an array of the provides-items this component is associated with.

#### Returns

A list of desktops where this component is compulsory.

[element-type utf8][transfer none]

### as_component_add_provided_item ()

    void
    as_component_add_provided_item (AsComponent *cpt,
                                    AsProvidesKind kind,
                                    const gchar *value,
                                    const gchar *data);

Adds a provided item to the component.

#### Parameters

cpt | a AsComponent instance. |
kind | the kind of the provided item (e.g. `AS_PROVIDES_KIND_MIMETYPE`) |
data | additional data associated with this item, or `NULL`. | [allow-none][default NULL]

Since: 0.6.2

### as_component_provides_item ()

    gboolean
    as_component_provides_item (AsComponent *cpt,
                                AsProvidesKind kind,
                                const gchar *value);

Checks if this component provides an item of the specified type

#### Parameters

cpt | a valid AsComponent |
kind | the kind of the provides-item |
value | the value of the provides-item |

#### Returns

`TRUE` if an item was found

### as_component_get_urls ()

    GHashTable *
    as_component_get_urls (AsComponent *cpt);

Gets the URLs set for the component.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

URLs.

[transfer none]

Since: 0.6.2

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

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.

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

#### Parameters

cpt | an AsComponent instance. |

#### Returns

an array.

[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 |

### 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" |
percentage | the percentage completion of the translation, 0 for locales with unknown amount of translation |

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" |

#### Returns

a percentage value, -1 if locale was not found

Since: 0.7.0

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

    GHashTable *
    as_component_get_bundle_ids (AsComponent *cpt);

Gets the bundle-ids set for the component.

#### Parameters

cpt | a AsComponent instance. |

#### Returns

Bundle ids.

[transfer none]

Since: 0.8.0

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

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

## Types and Values

### enum AsComponentKind

The URL type.

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

### enum AsIconKind

The icon type.

#### Members

AS_ICON_KIND_UNKNOWN |  |
AS_ICON_KIND_CACHED | Icon in the internal caches |
AS_ICON_KIND_STOCK | Stock icon name |
AS_ICON_KIND_LOCAL | Local icon name |
AS_ICON_KIND_REMOTE | Remote icon URL |
AS_ICON_KIND_LAST |  |

## Property Details

### The `“categories”` property

      “categories”               GStrv

categories.

Flags: Read / Write

### The `“description”` property

      “description”              gchar *

description.

Flags: Read / Write

Default value: NULL

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

      “developer-name”           gchar *

developer-name.

Flags: Read / Write

Default value: NULL

### The `“icon-urls”` property

      “icon-urls”                GHashTable *

icon-urls.

Flags: Read

### The `“id”` property

      “id”                       gchar *

id.

Flags: Read / Write

Default value: NULL

### The `“keywords”` property

      “keywords”                 GStrv

keywords.

Flags: Read / Write

### The `“kind”` property

      “kind”                     AsComponentKind

kind.

Flags: Read / Write

Default value: AS_COMPONENT_KIND_UNKNOWN

### The `“name”` property

      “name”                     gchar *

name.

Flags: Read / Write

Default value: NULL

### The `“pkgnames”` property

      “pkgnames”                 GStrv

pkgnames.

Flags: Read / Write

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

      “project-group”            gchar *

project-group.

Flags: Read / Write

Default value: NULL

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

      “project-license”          gchar *

project-license.

Flags: Read / Write

Default value: NULL

### The `“screenshots”` property

      “screenshots”              GPtrArray *

screenshots.

Flags: Read

### The `“summary”` property

      “summary”                  gchar *

summary.

Flags: Read / Write

Default value: NULL

### The `“urls”` property

      “urls”                     GHashTable *

urls.

Flags: Read