AppStream-glib Reference Manual: AsStore

## AsStore AsStore — a hashed array store of applications |

## Stability Level

Stable, unless otherwise indicated

## Functions

AsStore * | as_store_new ()
GQuark | as_store_error_quark ()
guint | as_store_get_size ()
gboolean | as_store_from_file ()
gboolean | as_store_from_xml ()
gboolean | as_store_load ()
gboolean | as_store_load_path ()
void | as_store_remove_all ()
GPtrArray * | as_store_get_apps ()
GPtrArray * | as_store_get_apps_by_metadata ()
AsApp * | as_store_get_app_by_id ()
AsApp * | as_store_get_app_by_pkgname ()
void | as_store_add_app ()
void | as_store_remove_app ()
GString * | as_store_to_xml ()
gboolean | as_store_to_file ()
const gchar * | as_store_get_origin ()
void | as_store_set_origin ()
const gchar * | as_store_get_builder_id ()
void | as_store_set_builder_id ()
const gchar * | as_store_get_destdir ()
void | as_store_set_destdir ()
gdouble | as_store_get_api_version ()
void | as_store_set_api_version ()
AsStoreAddFlags | as_store_get_add_flags ()
void | as_store_set_add_flags ()
GPtrArray * | as_store_validate ()

## Signals

void | changed | Run Last

## Types and Values

enum | AsStoreLoadFlags
enum | AsStoreAddFlags
enum | AsStoreError
#define | AS_STORE_ERROR

## Object Hierarchy

        GObject
        ╰── AsStore

## Includes

    #include <appstream-glib.h>

## Description

This store contains both an array of AsApp's but also a pair of hashes to quickly retrieve an application from the ID or package name.

Applications can also be removed, and the whole store can be loaded and saved to a compressed XML file.

See also: AsApp

## Functions

### as_store_new ()

    AsStore *
    as_store_new (void);

Creates a new AsStore.

#### Returns

a AsStore.

[transfer full]

Since 0.1.0

### as_store_error_quark ()

    GQuark
    as_store_error_quark (void);

#### Returns

An error quark.

Since 0.1.2

### as_store_get_size ()

    guint
    as_store_get_size (AsStore *store);

Gets the size of the store after deduplication and prioritization has taken place.

#### Parameters

store | a AsStore instance. |

#### Returns

the number of usable applications in the store

Since 0.1.0

### as_store_from_file ()

    gboolean
    as_store_from_file (AsStore *store,
                        GFile *file,
                        const gchar *icon_root,
                        GCancellable *cancellable,
                        GError **error);

Parses an AppStream XML or DEP-11 YAML file and adds any valid applications to the store.

If the root node does not have a 'origin' attribute, then the method `as_store_set_origin()` should be called *before* this function if cached icons are required.

#### Parameters

store | a AsStore instance. |
file | a GFile. |
icon_root | the icon path, or `NULL` for the default. |
cancellable | a GCancellable. |
error | A GError or `NULL`. |

#### Returns

`TRUE` for success

Since 0.1.0

### as_store_from_xml ()

    gboolean
    as_store_from_xml (AsStore *store,
                       const gchar *data,
                       gssize data_len,
                       const gchar *icon_root,
                       GError **error);

Parses AppStream XML file and adds any valid applications to the store.

If the root node does not have a 'origin' attribute, then the method `as_store_set_origin()` should be called *before* this function if cached icons are required.

#### Parameters

store | a AsStore instance. |
data | XML data |
data_len | Length of `data` , or -1 if NULL terminated |
icon_root | the icon path, or `NULL` for the default. |
error | A GError or `NULL`. |

#### Returns

`TRUE` for success

Since 0.1.1

### as_store_load ()

    gboolean
    as_store_load (AsStore *store,
                   AsStoreLoadFlags flags,
                   GCancellable *cancellable,
                   GError **error);

Loads the store from the default locations.

#### Parameters

store | a AsStore instance. |
flags | AsStoreLoadFlags, e.g. `AS_STORE_LOAD_FLAG_APP_INFO_SYSTEM` |
cancellable | a GCancellable. |
error | A GError or `NULL`. |

#### Returns

`TRUE` for success

Since 0.1.2

### as_store_load_path ()

    gboolean
    as_store_load_path (AsStore *store,
                        const gchar *path,
                        GCancellable *cancellable,
                        GError **error);

Loads the store from a specific path.

#### Parameters

store | a AsStore instance. |
path | A path to load |
cancellable | a GCancellable. |
error | A GError or `NULL`. |

#### Returns

`TRUE` for success

Since 0.2.2

### as_store_remove_all ()

    void
    as_store_remove_all (AsStore *store);

Removes all applications from the store.

#### Parameters

store | a AsStore instance. |

Since 0.2.5

### as_store_get_apps ()

    GPtrArray *
    as_store_get_apps (AsStore *store);

Gets an array of all the valid applications in the store.

#### Parameters

store | a AsStore instance. |

#### Returns

an array.

[element-type AsApp][transfer none]

Since 0.1.0

### as_store_get_apps_by_metadata ()

    GPtrArray *
    as_store_get_apps_by_metadata (AsStore *store,
                                   const gchar *key,
                                   const gchar *value);

Gets an array of all the applications that match a specific metadata element.

#### Parameters

store | a AsStore instance. |
key | metadata key |
value | metadata value |

#### Returns

an array.

[element-type AsApp][transfer container]

Since 0.1.4

### as_store_get_app_by_id ()

    AsApp *
    as_store_get_app_by_id (AsStore *store,
                            const gchar *id);

Finds an application in the store by ID.

#### Parameters

store | a AsStore instance. |
id | the application full ID. |

#### Returns

a AsApp or `NULL`.

[transfer none]

Since 0.1.0

### as_store_get_app_by_pkgname ()

    AsApp *
    as_store_get_app_by_pkgname (AsStore *store,
                                 const gchar *pkgname);

Finds an application in the store by package name.

#### Parameters

store | a AsStore instance. |
pkgname | the package name. |

#### Returns

a AsApp or `NULL`.

[transfer none]

Since 0.1.0

### as_store_add_app ()

    void
    as_store_add_app (AsStore *store,
                      AsApp *app);

Adds an application to the store. If a lower priority application has already been added then this new application will replace it.

Additionally only applications where the kind is known will be added.

#### Parameters

store | a AsStore instance. |
app | a AsApp instance. |

Since 0.1.0

### as_store_remove_app ()

    void
    as_store_remove_app (AsStore *store,
                         AsApp *app);

Removes an application from the store if it exists.

#### Parameters

store | a AsStore instance. |
app | a AsApp instance. |

Since 0.1.0

### as_store_to_xml ()

    GString *
    as_store_to_xml (AsStore *store,
                     AsNodeToXmlFlags flags);

Outputs an XML representation of all the applications in the store.

#### Parameters

store | a AsStore instance. |
flags | the AsNodeToXmlFlags, e.g. `AS_NODE_INSERT_FLAG_NONE`. |

#### Returns

A GString

Since 0.1.0

### as_store_to_file ()

    gboolean
    as_store_to_file (AsStore *store,
                      GFile *file,
                      AsNodeToXmlFlags flags,
                      GCancellable *cancellable,
                      GError **error);

Outputs a compressed XML file of all the applications in the store.

#### Parameters

store | a AsStore instance. |
file | file |
flags | the AsNodeToXmlFlags, e.g. `AS_NODE_INSERT_FLAG_NONE`. |
cancellable | A GCancellable, or `NULL` |
error | A GError or `NULL` |

#### Returns

A GString

Since 0.1.0

### as_store_get_origin ()

    const gchar *
    as_store_get_origin (AsStore *store);

Gets the metadata origin, which is used to locate icons.

#### Parameters

store | a AsStore instance. |

#### Returns

the origin string, or `NULL` if unset

Since 0.1.1

### as_store_set_origin ()

    void
    as_store_set_origin (AsStore *store,
                         const gchar *origin);

Sets the metadata origin, which is used to locate icons.

#### Parameters

store | a AsStore instance. |
origin | the origin, e.g. "fedora-21" |

Since 0.1.1

### as_store_get_builder_id ()

    const gchar *
    as_store_get_builder_id (AsStore *store);

Gets the metadata builder identifier, which is used to work out if old metadata is compatible with this builder.

#### Parameters

store | a AsStore instance. |

#### Returns

the builder_id string, or `NULL` if unset

Since 0.2.5

### as_store_set_builder_id ()

    void
    as_store_set_builder_id (AsStore *store,
                             const gchar *builder_id);

Sets the metadata builder identifier, which is used to work out if old metadata can be used.

#### Parameters

store | a AsStore instance. |
builder_id | the builder_id, e.g. "appstream-glib:1" |

Since 0.2.5

### as_store_get_destdir ()

    const gchar *
    as_store_get_destdir (AsStore *store);

Gets the destdir, which is used to prefix usr.

#### Parameters

store | a AsStore instance. |

#### Returns

the destdir path, or `NULL` if unset

Since 0.2.4

### as_store_set_destdir ()

    void
    as_store_set_destdir (AsStore *store,
                          const gchar *destdir);

Sets the destdir, which is used to prefix usr.

#### Parameters

store | a AsStore instance. |
destdir | the destdir, e.g. "/tmp" |

Since 0.2.4

### as_store_get_api_version ()

    gdouble
    as_store_get_api_version (AsStore *store);

Gets the AppStream API version.

#### Parameters

store | a AsStore instance. |

#### Returns

the AsNodeInsertFlags, or 0 if unset

Since 0.1.1

### as_store_set_api_version ()

    void
    as_store_set_api_version (AsStore *store,
                              gdouble api_version);

Sets the AppStream API version.

#### Parameters

store | a AsStore instance. |
api_version | the API version |

Since 0.1.1

### as_store_get_add_flags ()

    AsStoreAddFlags
    as_store_get_add_flags (AsStore *store);

Gets the flags used for adding applications to the store.

#### Parameters

store | a AsStore instance. |

#### Returns

the AsStoreAddFlags, or 0 if unset

Since 0.2.2

### as_store_set_add_flags ()

    void
    as_store_set_add_flags (AsStore *store,
                            AsStoreAddFlags add_flags);

Sets the flags used when adding applications to the store.

NOTE: Using `AS_STORE_ADD_FLAG_PREFER_LOCAL` may be a privacy risk depending on your level of paranoia, and should not be used by default.

#### Parameters

store | a AsStore instance. |
add_flags | the AsStoreAddFlags, e.g. `AS_STORE_ADD_FLAG_NONE` |

Since 0.2.2

### as_store_validate ()

    GPtrArray *
    as_store_validate (AsStore *store,
                       AsAppValidateFlags flags,
                       GError **error);

Validates infomation in the store for data applicable to the defined metadata version.

#### Parameters

store | a AsStore instance. |
flags | the AsAppValidateFlags to use, e.g. `AS_APP_VALIDATE_FLAG_NONE` |
error | A GError or `NULL`. |

#### Returns

A list of problems, or `NULL`.

[transfer container][element-type AsProblem]

Since 0.2.4

## Types and Values

### enum AsStoreLoadFlags

The flags to use when loading the store.

#### Members

AS_STORE_LOAD_FLAG_NONE | No extra flags to use |
AS_STORE_LOAD_FLAG_APP_INFO_SYSTEM | The system app-info AppStream data |
AS_STORE_LOAD_FLAG_APP_INFO_USER | The per-user app-info AppStream data |
AS_STORE_LOAD_FLAG_APP_INSTALL | The ubuntu-specific app-install data |
AS_STORE_LOAD_FLAG_APPDATA | The installed AppData files |
AS_STORE_LOAD_FLAG_DESKTOP | The installed desktop files |
AS_STORE_LOAD_FLAG_ALLOW_VETO | Add vetoed applications |

### enum AsStoreAddFlags

The flags to use when adding applications to the store.

#### Members

AS_STORE_ADD_FLAG_NONE | No extra flags to use |
AS_STORE_ADD_FLAG_PREFER_LOCAL | Local files will be used by default |

### enum AsStoreError

The error type.

#### Members

AS_STORE_ERROR_FAILED | Generic failure |

### AS_STORE_ERROR

    #define AS_STORE_ERROR				as_store_error_quark ()

## Signal Details

### The `“changed”` signal

    void
    user_function (AsStore *device,
                   gpointer user_data)

Flags: Run Last

Since 0.1.2