AsRelation: AppStream Library Reference Manual

## AsRelation AsRelation — Description of relations a software component has with other things |

## Functions

GQuark | as_relation_error_quark ()
const gchar * | as_relation_kind_to_string ()
AsRelationKind | as_relation_kind_from_string ()
const gchar * | as_relation_item_kind_to_string ()
AsRelationItemKind | as_relation_item_kind_from_string ()
AsRelationCompare | as_relation_compare_from_string ()
const gchar * | as_relation_compare_to_string ()
const gchar * | as_relation_compare_to_symbols_string ()
const gchar * | as_control_kind_to_string ()
AsControlKind | as_control_kind_from_string ()
const gchar * | as_display_side_kind_to_string ()
AsDisplaySideKind | as_display_side_kind_from_string ()
const gchar * | as_display_length_kind_to_string ()
AsDisplayLengthKind | as_display_length_kind_from_string ()
const gchar * | as_internet_kind_to_string ()
AsInternetKind | as_internet_kind_from_string ()
AsRelation * | as_relation_new ()
AsRelationKind | as_relation_get_kind ()
void | as_relation_set_kind ()
AsRelationItemKind | as_relation_get_item_kind ()
void | as_relation_set_item_kind ()
AsRelationCompare | as_relation_get_compare ()
void | as_relation_set_compare ()
const gchar * | as_relation_get_version ()
void | as_relation_set_version ()
const gchar * | as_relation_get_value_str ()
void | as_relation_set_value_str ()
gint | as_relation_get_value_int ()
void | as_relation_set_value_int ()
AsControlKind | as_relation_get_value_control_kind ()
void | as_relation_set_value_control_kind ()
AsDisplaySideKind | as_relation_get_display_side_kind ()
void | as_relation_set_display_side_kind ()
gint | as_relation_get_value_px ()
void | as_relation_set_value_px ()
AsDisplayLengthKind | as_relation_get_value_display_length_kind ()
void | as_relation_set_value_display_length_kind ()
AsInternetKind | as_relation_get_value_internet_kind ()
void | as_relation_set_value_internet_kind ()
guint | as_relation_get_value_internet_bandwidth ()
void | as_relation_set_value_internet_bandwidth ()
gboolean | as_relation_version_compare ()
AsCheckResult | as_relation_is_satisfied ()
const gchar * | as_relation_get_value ()
void | as_relation_set_value ()

## Types and Values

#define | AS_TYPE_RELATION
struct | AsRelationClass
enum | AsCheckResult
enum | AsRelationKind
enum | AsRelationItemKind
enum | AsRelationCompare
enum | AsControlKind
enum | AsDisplaySideKind
enum | AsDisplayLengthKind
enum | AsInternetKind
enum | AsRelationError
#define | AS_RELATION_ERROR
| AsPool
| AsRelation
| AsSystemInfo

## Includes

    #include <appstream.h>

## Description

A component can have recommends- or requires relations on other components, system properties, hardware and other interfaces. This class contains a representation of those relations.

See also: AsComponent

## Functions

### as_relation_error_quark ()

    GQuark
    as_relation_error_quark (void);

#### Returns

An error quark.

Since: 0.16.0

### as_relation_kind_to_string ()

    const gchar *
    as_relation_kind_to_string (AsRelationKind kind);

Converts the enumerated value to a text representation.

#### Parameters

kind | the AsRelationKind. |

#### Returns

string version of `kind`

Since: 0.12.0

### as_relation_kind_from_string ()

    AsRelationKind
    as_relation_kind_from_string (const gchar *kind_str);

Converts the text representation to an enumerated value.

#### Parameters

kind_str | the string. |

#### Returns

a AsRelationKind or `AS_RELATION_KIND_UNKNOWN` for unknown

Since: 0.12.0

### as_relation_item_kind_to_string ()

    const gchar *
    as_relation_item_kind_to_string (AsRelationItemKind kind);

Converts the enumerated value to a text representation.

#### Parameters

kind | the AsRelationKind. |

#### Returns

string version of `kind`

Since: 0.12.0

### as_relation_item_kind_from_string ()

    AsRelationItemKind
    as_relation_item_kind_from_string (const gchar *kind_str);

Converts the text representation to an enumerated value.

#### Parameters

kind_str | the string. |

#### Returns

a AsRelationItemKind or `AS_RELATION_ITEM_KIND_UNKNOWN` for unknown

Since: 0.12.0

### as_relation_compare_from_string ()

    AsRelationCompare
    as_relation_compare_from_string (const gchar *compare_str);

Converts the text representation to an enumerated value.

#### Parameters

compare_str | the string. |

#### Returns

a AsRelationCompare, or `AS_RELATION_COMPARE_UNKNOWN` for unknown.

Since: 0.12.0

### as_relation_compare_to_string ()

    const gchar *
    as_relation_compare_to_string (AsRelationCompare compare);

Converts the enumerated value to an text representation. The enum is converted into a two-letter identifier ("eq", "ge", etc.) for use in the XML representation.

#### Parameters

compare | the AsRelationCompare. |

#### Returns

string version of `compare`

Since: 0.12.0

### as_relation_compare_to_symbols_string ()

    const gchar *
    as_relation_compare_to_symbols_string (AsRelationCompare compare);

Converts the enumerated value to an text representation. The enum is converted into an identifier consisting of two mathematical comparison operators ("==", ">=", etc.) for use in the YAML representation and user interfaces.

#### Parameters

compare | the AsRelationCompare. |

#### Returns

string version of `compare`

Since: 0.12.0

### as_control_kind_to_string ()

    const gchar *
    as_control_kind_to_string (AsControlKind kind);

Converts the enumerated value to a text representation.

#### Parameters

kind | the AsControlKind. |

#### Returns

string version of `kind`

Since: 0.12.11

### as_control_kind_from_string ()

    AsControlKind
    as_control_kind_from_string (const gchar *kind_str);

Converts the text representation to an enumerated value.

#### Parameters

kind_str | the string. |

#### Returns

a AsControlKind or `AS_CONTROL_KIND_UNKNOWN` for unknown

Since: 0.12.11

### as_display_side_kind_to_string ()

    const gchar *
    as_display_side_kind_to_string (AsDisplaySideKind kind);

Converts the enumerated value to a text representation.

#### Parameters

kind | the AsDisplaySideKind. |

#### Returns

string version of `kind`

Since: 0.12.12

### as_display_side_kind_from_string ()

    AsDisplaySideKind
    as_display_side_kind_from_string (const gchar *kind_str);

Converts the text representation to an enumerated value.

#### Parameters

kind_str | the string. |

#### Returns

a AsDisplaySideKind or `AS_DISPLAY_SIDE_KIND_UNKNOWN` for unknown

Since: 0.12.12

### as_display_length_kind_to_string ()

    const gchar *
    as_display_length_kind_to_string (AsDisplayLengthKind kind);

Converts the enumerated value to a text representation.

#### Parameters

kind | the AsDisplayLengthKind. |

#### Returns

string version of `kind`

Since: 0.12.12

### as_display_length_kind_from_string ()

    AsDisplayLengthKind
    as_display_length_kind_from_string (const gchar *kind_str);

Converts the text representation to an enumerated value.

#### Parameters

kind_str | the string. |

#### Returns

a AsDisplayLengthKind or `AS_DISPLAY_LENGTH_KIND_UNKNOWN` for unknown

Since: 0.12.12

### as_internet_kind_to_string ()

    const gchar *
    as_internet_kind_to_string (AsInternetKind kind);

Converts the enumerated value to a text representation.

#### Parameters

kind | the AsInternetKind. |

#### Returns

string version of `kind`

Since: 0.15.5

### as_internet_kind_from_string ()

    AsInternetKind
    as_internet_kind_from_string (const gchar *kind_str);

Converts the text representation to an enumerated value.

#### Parameters

kind_str | the string. |

#### Returns

a AsInternetKind or `AS_INTERNET_KIND_UNKNOWN` for unknown

Since: 0.15.5

### as_relation_new ()

    AsRelation *
    as_relation_new (void);

Creates a new AsRelation.

#### Returns

a AsRelation.

[transfer full]

Since: 0.11.0

### as_relation_get_kind ()

    AsRelationKind
    as_relation_get_kind (AsRelation *relation);

The type (and thereby strength) of this AsRelation.

#### Parameters

relation | a AsRelation instance. |

#### Returns

an enum of type AsRelationKind

Since: 0.12.0

### as_relation_set_kind ()

    void
    as_relation_set_kind (AsRelation *relation,
                          AsRelationKind kind);

Set the kind of this AsRelation.

#### Parameters

relation | a AsRelation instance. |
kind | the new AsRelationKind |

Since: 0.12.0

### as_relation_get_item_kind ()

    AsRelationItemKind
    as_relation_get_item_kind (AsRelation *relation);

The kind of the item of this AsRelation.

#### Parameters

relation | a AsRelation instance. |

#### Returns

an enum of type AsRelationItemKind

Since: 0.12.0

### as_relation_set_item_kind ()

    void
    as_relation_set_item_kind (AsRelation *relation,
                               AsRelationItemKind kind);

Set the kind of the item this AsRelation is about.

#### Parameters

relation | a AsRelation instance. |
kind | the new AsRelationItemKind |

Since: 0.12.0

### as_relation_get_compare ()

    AsRelationCompare
    as_relation_get_compare (AsRelation *relation);

The version comparison type.

#### Parameters

relation | a AsRelation instance. |

#### Returns

an enum of type AsRelationCompare

Since: 0.12.0

### as_relation_set_compare ()

    void
    as_relation_set_compare (AsRelation *relation,
                             AsRelationCompare compare);

Set the version comparison type of this AsRelation.

#### Parameters

relation | an AsRelation instance. |
compare | the new AsRelationCompare |

Since: 0.12.0

### as_relation_get_version ()

    const gchar *
    as_relation_get_version (AsRelation *relation);

#### Parameters

relation | an AsRelation instance. |

#### Returns

The version of the item this AsRelation is about.

Since: 0.12.0

### as_relation_set_version ()

    void
    as_relation_set_version (AsRelation *relation,
                             const gchar *version);

Sets the item version.

#### Parameters

relation | an AsRelation instance. |
version | the new version. |

Since: 0.12.0

### as_relation_get_value_str ()

    const gchar *
    as_relation_get_value_str (AsRelation *relation);

#### Parameters

relation | an AsRelation instance. |

#### Returns

The value of the item this AsRelation is about, as a string.

Since: 0.12.12

### as_relation_set_value_str ()

    void
    as_relation_set_value_str (AsRelation *relation,
                               const gchar *value);

Sets the item value as a string, if the given item type of this AsRelation permits string values.

#### Parameters

relation | an AsRelation instance. |
value | the new value. |

Since: 0.12.12

### as_relation_get_value_int ()

    gint
    as_relation_get_value_int (AsRelation *relation);

#### Parameters

relation | an AsRelation instance. |

#### Returns

The value of this AsRelation item as an integer. Returns 0 if the value was no integer.

Since: 0.12.0

### as_relation_set_value_int ()

    void
    as_relation_set_value_int (AsRelation *relation,
                               gint value);

Sets the item value as an integer, if the given item type of this AsRelation permits integer values.

#### Parameters

relation | an AsRelation instance. |
value | the new value. |

Since: 0.12.12

### as_relation_get_value_control_kind ()

    AsControlKind
    as_relation_get_value_control_kind (AsRelation *relation);

Get the value of this AsRelation item as AsControlKind if the type of this relation is `AS_RELATION_ITEM_KIND_CONTROL`. Otherwise return `AS_CONTROL_KIND_UNKNOWN`

#### Parameters

relation | an AsRelation instance. |

#### Returns

a AsControlKind or `AS_CONTROL_KIND_UNKNOWN` in case the item is not of the right kind.

Since: 0.12.11

### as_relation_set_value_control_kind ()

    void
    as_relation_set_value_control_kind (AsRelation *relation,
                                        AsControlKind kind);

Set relation item value from an AsControlKind.

#### Parameters

relation | an AsRelation instance. |
kind | an AsControlKind |

Since: 0.12.12

### as_relation_get_display_side_kind ()

    AsDisplaySideKind
    as_relation_get_display_side_kind (AsRelation *relation);

Gets the display side kind, in case this item is of kind `AS_RELATION_ITEM_KIND_DISPLAY_LENGTH`

#### Parameters

relation | an AsRelation instance. |

#### Returns

a AsDisplaySideKind or `AS_DISPLAY_SIDE_KIND_UNKNOWN`

Since: 0.12.12

### as_relation_set_display_side_kind ()

    void
    as_relation_set_display_side_kind (AsRelation *relation,
                                       AsDisplaySideKind kind);

Sets the display side kind, in case this item is of kind `AS_RELATION_ITEM_KIND_DISPLAY_LENGTH`

#### Parameters

relation | an AsRelation instance. |
kind | the new AsDisplaySideKind. |

Since: 0.12.12

### as_relation_get_value_px ()

    gint
    as_relation_get_value_px (AsRelation *relation);

In case this AsRelation is of kind `AS_RELATION_ITEM_KIND_DISPLAY_LENGTH`, return the set logical pixel amount.

#### Parameters

relation | an AsRelation instance. |

#### Returns

The logical pixel amount for this display length, value <= 0 on error.

Since: 0.12.12

### as_relation_set_value_px ()

    void
    as_relation_set_value_px (AsRelation *relation,
                              gint logical_px);

Sets the item value as logical pixel count. This requires the relation to be of item kind `AS_RELATION_ITEM_KIND_DISPLAY_LENGTH`.

#### Parameters

relation | an AsRelation instance. |
logical_px | logical pixel count. |

Since: 0.12.12

### as_relation_get_value_display_length_kind ()

    AsDisplayLengthKind
    as_relation_get_value_display_length_kind
                                   (AsRelation *relation);

In case this AsRelation is of kind `AS_RELATION_ITEM_KIND_DISPLAY_LENGTH`, return the AsDisplayLengthKind.

#### Parameters

relation | an AsRelation instance. |

#### Returns

The AsDisplayLengthKind classification of the current pixel value, or `AS_DISPLAY_LENGTH_KIND_UNKNOWN` on error.

Since: 0.12.12

### as_relation_set_value_display_length_kind ()

    void
    as_relation_set_value_display_length_kind
                                   (AsRelation *relation,
                                    AsDisplayLengthKind kind);

Sets the item value as display length placeholder value. This requires the relation to be of item kind `AS_RELATION_ITEM_KIND_DISPLAY_LENGTH`.

#### Parameters

relation | an AsRelation instance. |
kind | the AsDisplayLengthKind |

Since: 0.12.12

### as_relation_get_value_internet_kind ()

    AsInternetKind
    as_relation_get_value_internet_kind (AsRelation *relation);

Get the value of this AsRelation item as AsInternetKind if the type of this relation is `AS_RELATION_ITEM_KIND_INTERNET`. Otherwise return `AS_INTERNET_KIND_UNKNOWN`

#### Parameters

relation | an AsRelation instance. |

#### Returns

a AsInternetKind or `AS_INTERNET_KIND_UNKNOWN` in case the item is not of the right kind.

Since: 0.15.5

### as_relation_set_value_internet_kind ()

    void
    as_relation_set_value_internet_kind (AsRelation *relation,
                                         AsInternetKind kind);

Set relation item value from an AsInternetKind.

#### Parameters

relation | an AsRelation instance. |
kind | an AsInternetKind |

Since: 0.15.5

### as_relation_get_value_internet_bandwidth ()

    guint
    as_relation_get_value_internet_bandwidth
                                   (AsRelation *relation);

If this AsRelation is of kind `AS_RELATION_ITEM_KIND_INTERNET`, return the minimum bandwidth requirement of the component, if set.

If the relation is of a different kind, or the requirement isn’t set, this returns `0`.

#### Parameters

relation | an AsRelation instance. |

#### Returns

The minimum bandwidth requirement, in Mbit/s.

Since: 0.15.5

### as_relation_set_value_internet_bandwidth ()

    void
    as_relation_set_value_internet_bandwidth
                                   (AsRelation *relation,
                                    guint bandwidth_mbitps);

### as_relation_version_compare ()

    gboolean
    as_relation_version_compare (AsRelation *relation,
                                 const gchar *version,
                                 GError **error);

Tests whether the version number of this AsRelation is fulfilled by `version` . Whether the given version is sufficient to fulfill the version requirement of this AsRelation is determined by its comparison resraint.

#### Parameters

relation | an AsRelation instance. |
version | a version number, e.g. `1.2.0` |
error | A GError or `NULL` |

#### Returns

`TRUE` if the version from the parameter is sufficient.

Since: 0.12.0

### as_relation_is_satisfied ()

    AsCheckResult
    as_relation_is_satisfied (AsRelation *relation,
                              AsSystemInfo *system_info,
                              AsPool *pool,
                              gchar **message,
                              GError **error);

Test if this relation is satisfied on the current system or with the provided AsPool. If no AsSystemInfo is found, a temporary one will be created. If no AsPool is provided, any component relationships can not be validated and an error will be thrown.

#### Parameters

relation | a AsRelation instance. |
system_info | an AsSystemInfo to use for system information. | [nullable]
pool | an AsPool to find component dependencies in. | [nullable]
message | receive a localized status message. | [out][optional]
error | a GError. |

#### Returns

`AS_CHECK_RESULT_TRUE` if the system satisfies the relation, `AS_CHECK_RESULT_ERROR` on error

### as_relation_get_value ()

    const gchar *
    as_relation_get_value (AsRelation *relation);

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

Deprecated method. Use `as_relation_get_value_str` instead.

#### Parameters

relation | an AsRelation instance. |

Since: 0.12.0

### as_relation_set_value ()

    void
    as_relation_set_value (AsRelation *relation,
                           const gchar *value);

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

Deprecated method. Use `as_relation_set_value_str` instead.

#### Parameters

relation | an AsRelation instance. |
value | the new value. |

Since: 0.12.0

## Types and Values

### AS_TYPE_RELATION

    #define AS_TYPE_RELATION (as_relation_get_type ())

### struct AsRelationClass

    struct AsRelationClass {
    	GObjectClass		parent_class;
    };

### enum AsCheckResult

Result of a check operation.

#### Members

AS_CHECK_RESULT_ERROR | The check failed. |
AS_CHECK_RESULT_UNKNOWN | The outcome could not be determined. |
AS_CHECK_RESULT_FALSE | False/No |
AS_CHECK_RESULT_TRUE | True/Yes |

### enum AsRelationKind

Type of a component's relation to other items.

#### Members

AS_RELATION_KIND_UNKNOWN | Unknown kind |
AS_RELATION_KIND_REQUIRES | The referenced item is required by the component |
AS_RELATION_KIND_RECOMMENDS | The referenced item is recommended |
AS_RELATION_KIND_SUPPORTS | The referenced item is supported |

### enum AsRelationItemKind

Type of the item an AsRelation is for.

#### Members

AS_RELATION_ITEM_KIND_UNKNOWN | Unknown kind |
AS_RELATION_ITEM_KIND_ID | A component ID |
AS_RELATION_ITEM_KIND_MODALIAS | A hardware modalias |
AS_RELATION_ITEM_KIND_KERNEL | An operating system kernel (like Linux) |
AS_RELATION_ITEM_KIND_MEMORY | A system RAM requirement |
AS_RELATION_ITEM_KIND_FIRMWARE | A device firmware requirement (used by fwupd) |
AS_RELATION_ITEM_KIND_CONTROL | An input method for users to control software |
AS_RELATION_ITEM_KIND_DISPLAY_LENGTH | Display edge length |
AS_RELATION_ITEM_KIND_HARDWARE | A Computer Hardware ID (CHID) to depend on system hardware |
AS_RELATION_ITEM_KIND_INTERNET | Internet connectivity (Since: 0.15.5) |

### enum AsRelationCompare

The relational comparison type.

#### Members

AS_RELATION_COMPARE_UNKNOWN | Comparison predicate invalid or not known |
AS_RELATION_COMPARE_EQ | Equal to |
AS_RELATION_COMPARE_NE | Not equal to |
AS_RELATION_COMPARE_LT | Less than |
AS_RELATION_COMPARE_GT | Greater than |
AS_RELATION_COMPARE_LE | Less than or equal to |
AS_RELATION_COMPARE_GE | Greater than or equal to |

### enum AsControlKind

Kind of an input method for users to control software

#### Members

AS_CONTROL_KIND_UNKNOWN | Unknown kind |
AS_CONTROL_KIND_POINTING | Mouse/cursors/other pointing device |
AS_CONTROL_KIND_KEYBOARD | Keyboard input |
AS_CONTROL_KIND_CONSOLE | Console / command-line interface |
AS_CONTROL_KIND_TOUCH | Touch input |
AS_CONTROL_KIND_GAMEPAD | Gamepad input (any game controller with wheels/buttons/joysticks) |
AS_CONTROL_KIND_VOICE | Control via voice recognition/activation |
AS_CONTROL_KIND_VISION | Computer vision / visual object and sign detection |
AS_CONTROL_KIND_TV_REMOTE | Input via a television remote |
AS_CONTROL_KIND_TABLET | Graphics tablet input |

### enum AsDisplaySideKind

Side a display_length requirement is for.

#### Members

AS_DISPLAY_SIDE_KIND_UNKNOWN | Unknown |
AS_DISPLAY_SIDE_KIND_SHORTEST | Shortest side of the display rectangle. |
AS_DISPLAY_SIDE_KIND_LONGEST | Longest side of the display rectangle. |

### enum AsDisplayLengthKind

A rough estimate of how large a given display length is.

#### Members

AS_DISPLAY_LENGTH_KIND_UNKNOWN | Unknown |
AS_DISPLAY_LENGTH_KIND_XSMALL | Very small display |
AS_DISPLAY_LENGTH_KIND_SMALL | Small display |
AS_DISPLAY_LENGTH_KIND_MEDIUM | Medium display |
AS_DISPLAY_LENGTH_KIND_LARGE | Large display |
AS_DISPLAY_LENGTH_KIND_XLARGE | Very large display |

### enum AsInternetKind

Different internet connectivity requirements or recommendations for an application.

#### Members

AS_INTERNET_KIND_UNKNOWN | Unknown |
AS_INTERNET_KIND_ALWAYS | Always requires/recommends internet |
AS_INTERNET_KIND_OFFLINE_ONLY | Application is offline-only |
AS_INTERNET_KIND_FIRST_RUN | Requires/Recommends internet on first run only |

Since: 0.15.5

### enum AsRelationError

The error type.

#### Members

AS_RELATION_ERROR_FAILED | Generic failure |
AS_RELATION_ERROR_BAD_VALUE | A metadata value was bad. |
AS_RELATION_ERROR_NOT_IMPLEMENTED | Some check was not (yet) implemented. |

### AS_RELATION_ERROR

    #define AS_RELATION_ERROR				as_relation_error_quark ()

### AsPool

    typedef struct _AsPool AsPool;

### AsRelation

    typedef struct _AsRelation AsRelation;

### AsSystemInfo

    typedef struct _AsSystemInfo AsSystemInfo;