AsStore: AppStream-glib Reference Manual

## 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_bytes ()
gboolean | as_store_from_xml ()
gboolean | as_store_load ()
gboolean | as_store_load_path ()
void | as_store_load_search_cache ()
void | as_store_set_search_match ()
void | as_store_remove_all ()
GPtrArray * | as_store_get_apps ()
GPtrArray * | as_store_get_apps_by_id ()
GPtrArray * | as_store_get_apps_by_metadata ()
AsApp * | as_store_get_app_by_id ()
AsApp * | as_store_get_app_by_unique_id ()
AsApp * | as_store_get_app_by_id_ignore_prefix ()
AsApp * | as_store_get_app_by_id_with_fallbacks ()
AsApp * | as_store_get_app_by_pkgname ()
AsApp * | as_store_get_app_by_pkgnames ()
AsApp * | as_store_get_app_by_provide ()
void | as_store_add_app ()
void | as_store_add_apps ()
void | as_store_remove_app ()
void | as_store_remove_app_by_id ()
void | as_store_remove_apps_with_veto ()
GString * | as_store_to_xml ()
gboolean | as_store_to_file ()
gboolean | as_store_convert_icons ()
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 ()
AsStoreWatchFlags | as_store_get_watch_flags ()
void | as_store_set_watch_flags ()
GPtrArray * | as_store_validate ()
void | as_store_add_metadata_index ()
void | as_store_add_filter ()
void | as_store_remove_filter ()

## Signals

void | app-added | Run Last
void | app-changed | Run Last
void | app-removed | Run Last
void | changed | Run Last

## Types and Values

#define | AS_TYPE_STORE
struct | AsStoreClass
enum | AsStoreLoadFlags
#define | AS_STORE_LOAD_FLAG_XDG_APP_USER
#define | AS_STORE_LOAD_FLAG_XDG_APP_SYSTEM
enum | AsStoreAddFlags
enum | AsStoreWatchFlags
enum | AsStoreSearchFlags
enum | AsStoreError
#define | AS_STORE_ERROR
| AsStore

## 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 (unused) |
cancellable | a GCancellable. |
error | A GError or `NULL`. |

#### Returns

`TRUE` for success

Since: 0.1.0

### as_store_from_bytes ()

    gboolean
    as_store_from_bytes (AsStore *store,
                         GBytes *bytes,
                         GCancellable *cancellable,
                         GError **error);

Parses an appstream store presented as an archive. This is typically a .cab file containing firmware files.

#### Parameters

store | a AsStore instance. |
bytes | a GBytes. |
cancellable | a GCancellable. |
error | A GError or `NULL`. |

#### Returns

`TRUE` for success

Since: 0.5.2

### as_store_from_xml ()

    gboolean
    as_store_from_xml (AsStore *store,
                       const gchar *data,
                       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 |
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_load_search_cache ()

    void
    as_store_load_search_cache (AsStore *store);

Populates the token cache for all applications in the store. This allows all the search keywords for all applications in the store to be pre-processed at one time in multiple threads rather than on demand.

Note: Calling `as_app_search_matches()` automatically generates the search cache for the AsApp object if it has not already been generated.

#### Parameters

store | a AsStore instance. |

Since: 0.6.5

### as_store_set_search_match ()

    void
    as_store_set_search_match (AsStore *store,
                               AsAppSearchMatch search_match);

Sets the token match fields. The bitfield given here is used to choose what is included in the token cache.

#### Parameters

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

Since: 0.6.5

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

    GPtrArray *
    as_store_get_apps_by_id (AsStore *store,
                             const gchar *id);

Gets an array of all the applications that match a specific ID, ignoring the prefix type.

#### Parameters

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

#### Returns

an array.

[element-type AsApp][transfer container]

Since: 0.5.12

### 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. If more than one application exists matching the specific ID, (for instance when using `AS_STORE_ADD_FLAG_USE_UNIQUE_ID`) then the first item that was added is returned.

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

    AsApp *
    as_store_get_app_by_unique_id (AsStore *store,
                                   const gchar *unique_id,
                                   AsStoreSearchFlags search_flags);

Finds an application in the store by matching the unique ID.

#### Parameters

store | a AsStore instance. |
unique_id | the application unique ID, e.g. `user/flatpak/gnome-apps-nightly/app/gimp.desktop/master` |
search_flags | the search flags, e.g. `AS_STORE_SEARCH_FLAG_USE_WILDCARDS` |

#### Returns

a AsApp or `NULL`.

[transfer none]

Since: 0.6.1

### as_store_get_app_by_id_ignore_prefix ()

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

Finds an application in the store ignoring the prefix type.

#### Parameters

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

#### Returns

a AsApp or `NULL`.

[transfer none]

Since: 0.5.12

### as_store_get_app_by_id_with_fallbacks ()

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

Finds an application in the store by either by the current desktop ID or a desktop ID that it has used previously. This allows upstream software to change their ID (e.g. from cheese.desktop to org.gnome.Cheese.desktop) without us duplicating entries in the software center.

#### Parameters

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

#### Returns

a AsApp or `NULL`.

[transfer none]

Since: 0.4.1

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

    AsApp *
    as_store_get_app_by_pkgnames (AsStore *store,
                                  gchar **pkgnames);

Finds an application in the store by any of the possible package names.

#### Parameters

store | a AsStore instance. |
pkgnames | the package names to find. |

#### Returns

a AsApp or `NULL`.

[transfer none]

Since: 0.4.1

### as_store_get_app_by_provide ()

    AsApp *
    as_store_get_app_by_provide (AsStore *store,
                                 AsProvideKind kind,
                                 const gchar *value);

Finds an application in the store by something that it provides.

#### Parameters

store | a AsStore instance. |
kind | the AsProvideKind |
value | the provide value, e.g. "com.hughski.ColorHug2.firmware" |

#### Returns

a AsApp or `NULL`.

[transfer none]

Since: 0.5.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_add_apps ()

    void
    as_store_add_apps (AsStore *store,
                       GPtrArray *apps);

Adds several applications to the store.

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

#### Parameters

store | a AsStore instance. |
apps | an array of apps. | [element-type AsApp]

Since: 0.6.4

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

    void
    as_store_remove_app_by_id (AsStore *store,
                               const gchar *id);

Removes an application from the store if it exists.

#### Parameters

store | a AsStore instance. |
id | an application id |

Since: 0.3.0

### as_store_remove_apps_with_veto ()

    void
    as_store_remove_apps_with_veto (AsStore *store);

Removes any applications from the store if they have any vetos.

#### Parameters

store | a AsStore instance. |

Since: 0.5.13

### 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 an optionally 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_convert_icons ()

    gboolean
    as_store_convert_icons (AsStore *store,
                            AsIconKind kind,
                            GError **error);

Converts all the icons in the store to a specific kind.

#### Parameters

store | a AsStore instance. |
kind | the AsIconKind, e.g. `AS_ICON_KIND_EMBEDDED`. |
error | A GError or `NULL` |

#### Returns

`TRUE` for success

Since: 0.3.1

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

    AsStoreWatchFlags
    as_store_get_watch_flags (AsStore *store);

Gets the flags used for adding files to the store.

#### Parameters

store | a AsStore instance. |

#### Returns

the AsStoreWatchFlags, or 0 if unset

Since: 0.4.2

### as_store_set_watch_flags ()

    void
    as_store_set_watch_flags (AsStore *store,
                              AsStoreWatchFlags watch_flags);

Sets the flags used when adding files to the store.

#### Parameters

store | a AsStore instance. |
watch_flags | the AsStoreWatchFlags, e.g. `AS_STORE_WATCH_FLAG_NONE` |

Since: 0.4.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

### as_store_add_metadata_index ()

    void
    as_store_add_metadata_index (AsStore *store,
                                 const gchar *key);

Adds a metadata index key.

NOTE: if applications are removed *all* the indexes will be invalid and will have to be re-added.

#### Parameters

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

Since: 0.3.0

### as_store_add_filter ()

    void
    as_store_add_filter (AsStore *store,
                         AsAppKind kind);

Adds a filter to the store so that only components of this type are loaded into the store. This may be useful if the client is only interested in certain types of component, or not interested in loading components it cannot process.

If no filter is set then all types of components are loaded.

#### Parameters

store | a AsStore instance. |
kind | a AsAppKind, e.g. `AS_APP_KIND_FIRMWARE` |

Since: 0.3.5

### as_store_remove_filter ()

    void
    as_store_remove_filter (AsStore *store,
                            AsAppKind kind);

Removed a filter from the store so that components of this type are no longer loaded into the store. This may be useful if the client is only interested in certain types of component.

If all filters are removed then all types of components are loaded.

#### Parameters

store | a AsStore instance. |
kind | a AsAppKind, e.g. `AS_APP_KIND_FIRMWARE` |

Since: 0.3.5

## Types and Values

### AS_TYPE_STORE

    #define AS_TYPE_STORE (as_store_get_type ())

### struct AsStoreClass

    struct AsStoreClass {
    	GObjectClass		parent_class;
    	void			(*changed) (AsStore *store);
    	void			(*app_added) (AsStore *store,
    						 AsApp		*app);
    	void			(*app_removed) (AsStore *store,
    						 AsApp		*app);
    	void			(*app_changed) (AsStore *store,
    						 AsApp		*app);
    };

### 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 (obsolete) |
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 |
AS_STORE_LOAD_FLAG_FLATPAK_USER | Add flatpak user applications (obsolete) |
AS_STORE_LOAD_FLAG_FLATPAK_SYSTEM | Add flatpak system applications (obsolete) |
AS_STORE_LOAD_FLAG_IGNORE_INVALID | Ignore invalid files |
AS_STORE_LOAD_FLAG_ONLY_UNCOMPRESSED | Ignore compressed files |
AS_STORE_LOAD_FLAG_ONLY_MERGE_APPS | Ignore non-wildcard matches |

### AS_STORE_LOAD_FLAG_XDG_APP_USER

    #define AS_STORE_LOAD_FLAG_XDG_APP_USER		AS_STORE_LOAD_FLAG_FLATPAK_USER

### AS_STORE_LOAD_FLAG_XDG_APP_SYSTEM

    #define AS_STORE_LOAD_FLAG_XDG_APP_SYSTEM AS_STORE_LOAD_FLAG_FLATPAK_SYSTEM

### 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 |
AS_STORE_ADD_FLAG_USE_UNIQUE_ID | Allow multiple apps with the same AppStream ID |
AS_STORE_ADD_FLAG_USE_MERGE_HEURISTIC | Use a heuristic when adding merge components |
AS_STORE_ADD_FLAG_ONLY_NATIVE_LANGS | Only load native languages |

### enum AsStoreWatchFlags

The flags to use when local files are added or removed from the store.

#### Members

AS_STORE_WATCH_FLAG_NONE | No extra flags to use |
AS_STORE_WATCH_FLAG_ADDED | Add applications if files change or are added |
AS_STORE_WATCH_FLAG_REMOVED | Remove applications if files are changed or deleted |

### enum AsStoreSearchFlags

The flags to use when searching in the store.

#### Members

AS_STORE_SEARCH_FLAG_NONE | No extra flags to use |
AS_STORE_SEARCH_FLAG_USE_WILDCARDS | Process the globs |

### enum AsStoreError

The error type.

#### Members

AS_STORE_ERROR_FAILED | Generic failure |

### AS_STORE_ERROR

    #define AS_STORE_ERROR				as_store_error_quark ()

### AsStore

    typedef struct _AsStore AsStore;

## Signal Details

### The `“app-added”` signal

    void
    user_function (AsStore *store,
                   AsApp   *app,
                   gpointer user_data)

The ::app-added signal is emitted when a component has been added to the store.

#### Parameters

store | the AsStore instance that emitted the signal |
app | the AsApp instance |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.6.5

### The `“app-changed”` signal

    void
    user_function (AsStore *store,
                   AsApp   *app,
                   gpointer user_data)

The ::app-changed signal is emitted when a component has been changed in the store.

#### Parameters

store | the AsStore instance that emitted the signal |
app | the AsApp instance |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.6.5

### The `“app-removed”` signal

    void
    user_function (AsStore *store,
                   AsApp   *app,
                   gpointer user_data)

The ::app-removed signal is emitted when a component has been removed from the store.

#### Parameters

store | the AsStore instance that emitted the signal |
app | the AsApp instance |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.6.5

### The `“changed”` signal

    void
    user_function (AsStore *store,
                   gpointer user_data)

The ::changed signal is emitted when components have been added or removed from the store.

#### Parameters

store | the AsStore instance that emitted the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.1.2