AsStore

AsStore — a hashed array store of applications

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <appstream-glib.h>

enum                AsStoreLoadFlags;
enum                AsStoreAddFlags;
enum                AsStoreError;
#define             AS_STORE_ERROR
AsStore *           as_store_new                        (void);
GQuark              as_store_error_quark                (void);
guint               as_store_get_size                   (AsStore *store);
gboolean            as_store_from_file                  (AsStore *store,
                                                         GFile *file,
                                                         const gchar *icon_root,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            as_store_from_xml                   (AsStore *store,
                                                         const gchar *data,
                                                         gssize data_len,
                                                         const gchar *icon_root,
                                                         GError **error);
gboolean            as_store_load                       (AsStore *store,
                                                         AsStoreLoadFlags flags,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            as_store_load_path                  (AsStore *store,
                                                         const gchar *path,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                as_store_remove_all                 (AsStore *store);
GPtrArray *         as_store_get_apps                   (AsStore *store);
GPtrArray *         as_store_get_apps_by_metadata       (AsStore *store,
                                                         const gchar *key,
                                                         const gchar *value);
AsApp *             as_store_get_app_by_id              (AsStore *store,
                                                         const gchar *id);
AsApp *             as_store_get_app_by_id_with_fallbacks
                                                        (AsStore *store,
                                                         const gchar *id);
AsApp *             as_store_get_app_by_pkgname         (AsStore *store,
                                                         const gchar *pkgname);
AsApp *             as_store_get_app_by_pkgnames        (AsStore *store,
                                                         gchar **pkgnames);
void                as_store_add_app                    (AsStore *store,
                                                         AsApp *app);
void                as_store_remove_app                 (AsStore *store,
                                                         AsApp *app);
void                as_store_remove_app_by_id           (AsStore *store,
                                                         const gchar *id);
GString *           as_store_to_xml                     (AsStore *store,
                                                         AsNodeToXmlFlags flags);
gboolean            as_store_to_file                    (AsStore *store,
                                                         GFile *file,
                                                         AsNodeToXmlFlags flags,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            as_store_convert_icons              (AsStore *store,
                                                         AsIconKind kind,
                                                         GError **error);
const gchar *       as_store_get_origin                 (AsStore *store);
void                as_store_set_origin                 (AsStore *store,
                                                         const gchar *origin);
const gchar *       as_store_get_builder_id             (AsStore *store);
void                as_store_set_builder_id             (AsStore *store,
                                                         const gchar *builder_id);
const gchar *       as_store_get_destdir                (AsStore *store);
void                as_store_set_destdir                (AsStore *store,
                                                         const gchar *destdir);
gdouble             as_store_get_api_version            (AsStore *store);
void                as_store_set_api_version            (AsStore *store,
                                                         gdouble api_version);
AsStoreAddFlags     as_store_get_add_flags              (AsStore *store);
void                as_store_set_add_flags              (AsStore *store,
                                                         AsStoreAddFlags add_flags);
GPtrArray *         as_store_validate                   (AsStore *store,
                                                         AsAppValidateFlags flags,
                                                         GError **error);
void                as_store_add_metadata_index         (AsStore *store,
                                                         const gchar *key);
void                as_store_add_filter                 (AsStore *store,
                                                         AsIdKind kind);
void                as_store_remove_filter              (AsStore *store,
                                                         AsIdKind kind);

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

Details

enum AsStoreLoadFlags

typedef enum {
	AS_STORE_LOAD_FLAG_NONE			= 0, /* Since: 0.1.2 */
	AS_STORE_LOAD_FLAG_APP_INFO_SYSTEM = 1, /* Since: 0.1.2 */
	AS_STORE_LOAD_FLAG_APP_INFO_USER = 2, /* Since: 0.1.2 */
	AS_STORE_LOAD_FLAG_APP_INSTALL		= 4, /* Since: 0.1.2 */
	AS_STORE_LOAD_FLAG_APPDATA		= 8, /* Since: 0.2.2 */
	AS_STORE_LOAD_FLAG_DESKTOP		= 16, /* Since: 0.2.2 */
	AS_STORE_LOAD_FLAG_ALLOW_VETO		= 32, /* Since: 0.2.5 */
} AsStoreLoadFlags;

The flags to use when loading the store.

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

typedef enum {
	AS_STORE_ADD_FLAG_NONE			= 0, /* Since: 0.2.2 */
	AS_STORE_ADD_FLAG_PREFER_LOCAL		= 1, /* Since: 0.2.2 */
} AsStoreAddFlags;

The flags to use when adding applications to the store.

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

typedef enum {
	AS_STORE_ERROR_FAILED,
} AsStoreError;

The error type.

AS_STORE_ERROR_FAILED

Generic failure

AS_STORE_ERROR

#define AS_STORE_ERROR				as_store_error_quark ()

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

store :

a AsStore instance.

pkgnames :

the package names to find.

Returns :

a AsApp or NULL. [transfer none]

Since 0.4.1


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.

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.

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.

store :

a AsStore instance.

id :

an application id

Since 0.3.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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

store :

a AsStore instance.

key :

the metadata key.

Since 0.3.0


as_store_add_filter ()

void                as_store_add_filter                 (AsStore *store,
                                                         AsIdKind 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.

store :

a AsStore instance.

kind :

a AsIdKind, e.g. AS_ID_KIND_FIRMWARE

Since 0.3.5


as_store_remove_filter ()

void                as_store_remove_filter              (AsStore *store,
                                                         AsIdKind 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.

store :

a AsStore instance.

kind :

a AsIdKind, e.g. AS_ID_KIND_FIRMWARE

Since 0.3.5