AsPool

AsPool — Access the AppStream metadata pool.

Functions

Types and Values

Description

This class loads AppStream metadata from various sources and refines it with existing knowledge about the system (e.g. by setting absolute paths for cached icons). An AsPool will use an on-disk cache to store metadata is has read and refined to speed up the loading time when the same data is requested a second time.

You can find AppStream metadata matching various user-defined criteria, and also add new metadata to the pool. The caching behavior can be controlled by the application using AsCacheFlags.

An AppStream cache object can also be created and read using the appstreamcli(1) utility.

This class is threadsafe.

See also: AsComponent

Functions

as_pool_error_quark ()

GQuark
as_pool_error_quark (void);

Returns

An error quark.


as_pool_new ()

AsPool *
as_pool_new (void);

Creates a new AsPool.

Returns

a AsPool.

[transfer full]


as_pool_get_locale ()

const gchar *
as_pool_get_locale (AsPool *pool);

Gets the currently used locale.

Parameters

pool

An instance of AsPool.

 

Returns

Locale used for metadata parsing.


as_pool_set_locale ()

void
as_pool_set_locale (AsPool *pool,
                    const gchar *locale);

Sets the current locale which should be used when parsing metadata.

Parameters

pool

An instance of AsPool.

 

locale

the locale.

 

as_pool_load ()

gboolean
as_pool_load (AsPool *pool,
              GCancellable *cancellable,
              GError **error);

Builds an index of all found components in the watched locations. The function will try to get as much data into the pool as possible, so even if the update completes with FALSE, it might still have added components to the pool.

The function will load from all possible data sources, preferring caches if they are up to date.

Parameters

pool

An instance of AsPool.

 

cancellable

a GCancellable.

 

error

A GError or NULL.

 

Returns

TRUE if update completed without error.


as_pool_load_async ()

void
as_pool_load_async (AsPool *pool,
                    GCancellable *cancellable,
                    GAsyncReadyCallback callback,
                    gpointer user_data);

Asynchronously loads data from all registered locations. Equivalent to as_pool_load() (but asynchronous)

Parameters

pool

An instance of AsPool.

 

cancellable

a GCancellable.

 

callback

A GAsyncReadyCallback

 

user_data

Data to pass to callback

 

Since: 0.12.10


as_pool_load_finish ()

gboolean
as_pool_load_finish (AsPool *pool,
                     GAsyncResult *result,
                     GError **error);

Retrieve the result of as_pool_load_async().

Parameters

pool

An instance of AsPool.

 

result

A GAsyncResult

 

error

A GError or NULL.

 

Returns

TRUE for success

Since: 0.12.10


as_pool_clear2 ()

gboolean
as_pool_clear2 (AsPool *pool,
                GError **error);

Remove all metadata from the pool and clear caches.

Parameters

pool

An AsPool.

 

as_pool_add_component ()

gboolean
as_pool_add_component (AsPool *pool,
                       AsComponent *cpt,
                       GError **error);

Register a new component in the AppStream metadata pool.

Parameters

pool

An instance of AsPool

 

cpt

The AsComponent to add to the pool.

 

error

A GError or NULL

 

Returns

TRUE if the new component was successfully added to the pool.


as_pool_get_components ()

GPtrArray *
as_pool_get_components (AsPool *pool);

Get a list of found components.

Parameters

pool

An instance of AsPool.

 

Returns

an array of AsComponent instances.

[transfer container][element-type AsComponent]


as_pool_get_components_by_id ()

GPtrArray *
as_pool_get_components_by_id (AsPool *pool,
                              const gchar *cid);

Get a specific component by its ID. This function may contain multiple results if we have data describing this component from multiple scopes/origin types.

Parameters

pool

An instance of AsPool.

 

cid

The AppStream-ID to look for.

 

Returns

An AsComponent.

[transfer container][element-type AsComponent]


as_pool_get_components_by_provided_item ()

GPtrArray *
as_pool_get_components_by_provided_item
                               (AsPool *pool,
                                AsProvidedKind kind,
                                const gchar *item);

Find components in the AppStream data pool which provide a certain item.

Parameters

pool

An instance of AsPool.

 

kind

An AsProvidesKind

 

item

The value of the provided item.

 

Returns

an array of AsComponent objects which have been found.

[transfer container][element-type AsComponent]


as_pool_get_components_by_kind ()

GPtrArray *
as_pool_get_components_by_kind (AsPool *pool,
                                AsComponentKind kind);

Return a list of all components in the pool which are of a certain kind.

Parameters

pool

An instance of AsDatabase.

 

kind

An AsComponentKind.

 

Returns

an array of AsComponent objects which have been found.

[transfer container][element-type AsComponent]


as_pool_get_components_by_categories ()

GPtrArray *
as_pool_get_components_by_categories (AsPool *pool,
                                      gchar **categories);

Return a list of components which are in one of the categories.

Parameters

pool

An instance of AsDatabase.

 

categories

An array of XDG categories to include.

 

Returns

an array of AsComponent objects which have been found.

[transfer container][element-type AsComponent]


as_pool_get_components_by_launchable ()

GPtrArray *
as_pool_get_components_by_launchable (AsPool *pool,
                                      AsLaunchableKind kind,
                                      const gchar *id);

Find components in the AppStream data pool which provide a specific launchable. See AsLaunchable for details on launchables, or refer to the AppStream specification.

Parameters

pool

An instance of AsPool.

 

kind

An AsLaunchableKind

 

id

The ID of the launchable.

 

Returns

an array of AsComponent objects which have been found.

[transfer container][element-type AsComponent]

Since: 0.11.4


as_pool_search ()

GPtrArray *
as_pool_search (AsPool *pool,
                const gchar *search);

Search for a list of components matching the search term. The list will be ordered by match score.

Parameters

pool

An instance of AsPool

 

search

A search string

 

Returns

an array of the found AsComponent objects.

[transfer container][element-type AsComponent]

Since: 0.9.7


as_pool_build_search_tokens ()

gchar **
as_pool_build_search_tokens (AsPool *pool,
                             const gchar *search);

Splits up a string into an array of tokens that are suitable for searching. This includes stripping whitespaces, casefolding the terms and removing greylist words.

This function is usually called automatically when needed, you will only need to run it explicitly when you need to check which search tokens the pool will actually use internally for a given phrase.

Parameters

pool

An instance of AsPool.

 

search

the (user-provided) search phrase.

 

Returns

Valid tokens to search for, or NULL for error.

[transfer full]


as_pool_clear_metadata_locations ()

void
as_pool_clear_metadata_locations (AsPool *pool);

Remove all metadata locations from the list of watched locations.

Parameters

pool

An instance of AsPool.

 

as_pool_add_metadata_location ()

void
as_pool_add_metadata_location (AsPool *pool,
                               const gchar *directory);

Add a location for the data pool to read data from. If directory contains a "xml", "xmls", "yaml" or "icons" subdirectory (or all of them), those paths will be added to the search paths instead.

Parameters

pool

An instance of AsPool.

 

directory

An existing filesystem location.

 

as_pool_get_cache_flags ()

AsCacheFlags
as_pool_get_cache_flags (AsPool *pool);

Get the AsCacheFlags for this data pool.

Parameters

pool

An instance of AsPool.

 

as_pool_set_cache_flags ()

void
as_pool_set_cache_flags (AsPool *pool,
                         AsCacheFlags flags);

Set the AsCacheFlags for this data pool.

Parameters

pool

An instance of AsPool.

 

flags

The new AsCacheFlags.

 

as_pool_get_flags ()

AsPoolFlags
as_pool_get_flags (AsPool *pool);

Get the AsPoolFlags for this data pool.

Parameters

pool

An instance of AsPool.

 

as_pool_set_flags ()

void
as_pool_set_flags (AsPool *pool,
                   AsPoolFlags flags);

Set the AsPoolFlags for this data pool.

Parameters

pool

An instance of AsPool.

 

flags

The new AsPoolFlags.

 

as_pool_get_cache_location ()

const gchar *
as_pool_get_cache_location (AsPool *pool);

Gets the location of the session cache.

Parameters

pool

An instance of AsPool.

 

Returns

Location of the cache.


as_pool_set_cache_location ()

void
as_pool_set_cache_location (AsPool *pool,
                            const gchar *fname);

Sets the name of the cache file. If fname is ":memory", the cache will be kept in memory, if it is set to ":temporary", the cache will be stored in a temporary directory. In any other case, the given filename is used.

Parameters

pool

An instance of AsPool.

 

fname

Filename of the cache file, or special identifier.

 

Since: 0.12.7


as_pool_load_cache_file ()

gboolean
as_pool_load_cache_file (AsPool *pool,
                         const gchar *fname,
                         GError **error);

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

Load AppStream metadata from a cache file.

Parameters

pool

An instance of AsPool.

 

fname

Filename of the cache file to load into the pool.

 

error

A GError or NULL.

 

as_pool_save_cache_file ()

gboolean
as_pool_save_cache_file (AsPool *pool,
                         const gchar *fname,
                         GError **error);

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

Serialize AppStream metadata to a cache file.

Parameters

pool

An instance of AsPool.

 

fname

Filename of the cache file the pool contents should be dumped to.

 

error

A GError or NULL.

 

as_pool_refresh_cache ()

gboolean
as_pool_refresh_cache (AsPool *pool,
                       gboolean force,
                       GError **error);

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

Update the AppStream cache. There is normally no need to call this function manually, because cache updates are handled transparently in the background.

Parameters

pool

An instance of AsPool.

 

force

Enforce refresh, even if source data has not changed.

 

Returns

TRUE if the cache was updated, FALSE on error or if the cache update was not necessary and has been skipped.


as_pool_clear ()

void
as_pool_clear (AsPool *pool);

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

Remove all metadat from the pool.

Parameters

pool

An AsPool.

 

Types and Values

AS_TYPE_POOL

#define AS_TYPE_POOL (as_pool_get_type ())

struct AsPoolClass

struct AsPoolClass {
	GObjectClass parent_class;
};

enum AsCacheFlags

Flags on how caching should be used.

Members

AS_CACHE_FLAG_NONE

No flags.

 

AS_CACHE_FLAG_USE_USER

Create an user-specific metadata cache.

 

AS_CACHE_FLAG_USE_SYSTEM

Use and - if possible - update the system metadata cache.

 

AS_CACHE_FLAG_NO_CLEAR

Don't clear the cache when opening it.

 

AS_CACHE_FLAG_REFRESH_SYSTEM

Refresh the system cache that is shared between applications.

 

enum AsPoolFlags

Flags on how caching should be used.

Members

AS_POOL_FLAG_NONE

No flags.

 

AS_POOL_FLAG_READ_COLLECTION

Add AppStream collection metadata to the pool.

 

AS_POOL_FLAG_READ_METAINFO

Add data from AppStream metainfo files to the pool.

 

AS_POOL_FLAG_READ_DESKTOP_FILES

Add metadata from .desktop files to the pool.

 

enum AsPoolError

A metadata pool error.

Members

AS_POOL_ERROR_FAILED

Generic failure

 

AS_POOL_ERROR_TARGET_NOT_WRITABLE

We do not have write-access to the cache target location.

 

AS_POOL_ERROR_INCOMPLETE

The pool was loaded, but we had to ignore some metadata.

 

AS_POOL_ERROR_COLLISION

An AppStream-ID collision occured (a component with that ID already existed in the pool)

 

AS_POOL_ERROR_OLD_CACHE

Some issue with an old on-disk cache occured.

 

AS_POOL_ERROR

#define AS_POOL_ERROR as_pool_error_quark ()

AsPool

typedef struct _AsPool AsPool;