AsPool: AppStream Library Reference Manual

## AsPool AsPool — Access the AppStream metadata pool. |

## Functions

GQuark | as_pool_error_quark ()
AsPool * | as_pool_new ()
const gchar * | as_pool_get_locale ()
void | as_pool_set_locale ()
gboolean | as_pool_load ()
void | as_pool_load_async ()
gboolean | as_pool_load_finish ()
gboolean | as_pool_is_empty ()
void | as_pool_clear ()
gboolean | as_pool_add_components ()
GPtrArray * | as_pool_get_components ()
GPtrArray * | as_pool_get_components_by_id ()
GPtrArray * | as_pool_get_components_by_provided_item ()
GPtrArray * | as_pool_get_components_by_kind ()
GPtrArray * | as_pool_get_components_by_categories ()
GPtrArray * | as_pool_get_components_by_launchable ()
GPtrArray * | as_pool_get_components_by_extends ()
GPtrArray * | as_pool_get_components_by_bundle_id ()
GPtrArray * | as_pool_search ()
gchar ** | as_pool_build_search_tokens ()
void | as_pool_reset_extra_data_locations ()
void | as_pool_add_extra_data_location ()
AsPoolFlags | as_pool_get_flags ()
void | as_pool_set_flags ()
void | as_pool_add_flags ()
void | as_pool_remove_flags ()
void | as_pool_set_load_std_data_locations ()
gboolean | as_pool_add_component ()
gboolean | as_pool_load_cache_file ()
gboolean | as_pool_save_cache_file ()
gboolean | as_pool_refresh_cache ()
gboolean | as_pool_clear2 ()
const gchar * | as_pool_get_cache_location ()
void | as_pool_set_cache_location ()
AsCacheFlags | as_pool_get_cache_flags ()
void | as_pool_set_cache_flags ()
void | as_pool_clear_metadata_locations ()
void | as_pool_add_metadata_location ()

## Types and Values

#define | AS_TYPE_POOL
struct | AsPoolClass
enum | AsPoolFlags
#define | AS_POOL_FLAG_LOAD_OS_COLLECTION
#define | AS_POOL_FLAG_READ_COLLECTION
#define | AS_POOL_FLAG_READ_METAINFO
#define | AS_POOL_FLAG_READ_DESKTOP_FILES
enum | AsCacheFlags
enum | AsPoolError
#define | AS_POOL_ERROR
| AsPool

## 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 BCP47 or POSIX locale to use for this pool. |

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

    gboolean
    as_pool_is_empty (AsPool *pool);

Check if this pool contains any data.

#### Parameters

pool | An instance of AsPool. |

#### Returns

`TRUE` if the pool is empty.

### as_pool_clear ()

    void
    as_pool_clear (AsPool *pool);

Remove all metadata from the pool, data will be reloaded once `as_pool_load` is called again.

#### Parameters

pool | An AsPool. |

### as_pool_add_components ()

    gboolean
    as_pool_add_components (AsPool *pool,
                            GPtrArray *cpts,
                            GError **error);

Register a set of components with the pool temporarily. Data from components added like this will not be cached.

#### Parameters

pool | An instance of AsPool |
cpts | Array of components to add to the pool. | [element-type AsComponent]
error | A GError or `NULL` |

#### Returns

`TRUE` if the new components were successfully added to the pool.

Since: 0.15.0

### as_pool_get_components ()

    GPtrArray *
    as_pool_get_components (AsPool *pool);

Get a list of found components.

[skip]

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

[skip]

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

[skip]

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

[skip]

#### 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 all of the categories.

[skip]

#### Parameters

pool | An instance of AsDatabase. |
categories | An array of XDG categories to include. | [array zero-terminated=1]

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

[skip]

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

    GPtrArray *
    as_pool_get_components_by_extends (AsPool *pool,
                                       const gchar *extended_id);

Find components extending the component with the given ID. They can then be registered to the AsComponent they extend via `as_component_add_addon`. If the `AS_POOL_FLAG_RESOLVE_ADDONS` pool flag is set, addons are automatically resolved and this explicit function is not needed, but overall query time will be increased (so only use this flag if you will be resolving addon information later anyway).

[skip]

#### Parameters

pool | An instance of AsPool. |
extended_id | The ID of the component to search extensions for. |

#### Returns

an array of AsComponent objects.

[transfer container][element-type AsComponent]

Since: 0.15.0

### as_pool_get_components_by_bundle_id ()

    GPtrArray *
    as_pool_get_components_by_bundle_id (AsPool *pool,
                                         AsBundleKind kind,
                                         const gchar *bundle_id,
                                         gboolean match_prefix);

Find components that are provided by a bundle with a specific ID by its prefix. For example, given a AS_BUNDLE_KIND_FLATPAK and a bundle_id "org.kde.dolphin/", it will list all the components that bundle dolphin. If the bundle_id is "org.kde.dolphin/x86_64" it will give those with also the architecture.

[skip]

#### Parameters

pool | An instance of AsPool. |
kind | The kind of the bundle we are looking for |
bundle_id | The bundle ID to match, as specified in AsBundle |
match_prefix | `TRUE` to match the ID by prefix, `FALSE` to perform an absolute match. |

Since: 0.16.0

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

[skip]

#### 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

(array zero-terminated=1): Valid tokens to search for, or `NULL` for error.

[transfer full]

### as_pool_reset_extra_data_locations ()

    void
    as_pool_reset_extra_data_locations (AsPool *pool);

Remove all explicitly added metadata locations.

#### Parameters

pool | An instance of AsPool. |

Since: 0.15.0

### as_pool_add_extra_data_location ()

    void
    as_pool_add_extra_data_location (AsPool *pool,
                                     const gchar *directory,
                                     AsFormatStyle format_style);

Add an additional non-standard location to the metadata pool where metadata will be read 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. |
format_style | The expected format style of the metadata, e.g. `AS_FORMAT_STYLE_CATALOG` |

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

    void
    as_pool_add_flags (AsPool *pool,
                       AsPoolFlags flags);

Convenience function to add one or multiple AsPoolFlags to the flag set of this data pool.

#### Parameters

pool | An instance of AsPool. |
flags | The AsPoolFlags to add. |

Since: 0.15.0

### as_pool_remove_flags ()

    void
    as_pool_remove_flags (AsPool *pool,
                          AsPoolFlags flags);

Convenience function to remove one or multiple AsPoolFlags from the flag set of this data pool.

#### Parameters

pool | An instance of AsPool. |
flags | The AsPoolFlags to remove. |

Since: 0.15.0

### as_pool_set_load_std_data_locations ()

    void
    as_pool_set_load_std_data_locations (AsPool *pool,
                                         gboolean enabled);

This is a convenience function that enables or disables loading of metadata from well-known standard locations by configuring the AsPoolFlags of this AsPool accordingly. Data affected by this includes the OS data catalog, metainfo, desktop-entry files and Flatpak data. If you need more fine-grained control, set the AsPoolFlags explicitly.

#### Parameters

pool | An instance of AsPool. |
enabled | Whether loading of data from standard locations should be enabled. |

Since: 0.15.0

### as_pool_add_component ()

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

`as_pool_add_component` has been deprecated since version 0.15.0 and should not be used in newly-written code.

This function is very inefficient. Collect all the components you need to add, and then register them with `as_pool_add_components` in one go.

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_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` on success, `FALSE` on error.

### as_pool_clear2 ()

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

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

Remove all metadata from the pool.

#### Parameters

pool | An AsPool. |

### as_pool_get_cache_location ()

    const gchar *
    as_pool_get_cache_location (AsPool *pool);

`as_pool_get_cache_location` has been deprecated since version 0.15.0 and should not be used in newly-written code.

Cache location can no longer be set explicitly.

Gets the location of the session cache.

#### Parameters

pool | An instance of AsPool. |

#### Returns

Location of the cache, or `NULL` if unknown.

### as_pool_set_cache_location ()

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

`as_pool_set_cache_location` has been deprecated since version 0.15.0 and should not be used in newly-written code.

Cache location can no longer be set explicitly.

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_get_cache_flags ()

    AsCacheFlags
    as_pool_get_cache_flags (AsPool *pool);

`as_pool_get_cache_flags` has been deprecated since version 0.15.0 and should not be used in newly-written code.

Cache flags can no longer be changed.

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);

`as_pool_set_cache_flags` has been deprecated since version 0.15.0 and should not be used in newly-written code.

Cache flags can no longer be modified.

Set the AsCacheFlags for this data pool.

#### Parameters

pool | An instance of AsPool. |
flags | The new AsCacheFlags. |

### as_pool_clear_metadata_locations ()

    void
    as_pool_clear_metadata_locations (AsPool *pool);

`as_pool_clear_metadata_locations` has been deprecated since version 0.15.0 and should not be used in newly-written code.

Use `as_pool_reset_extra_data_locations` and control system data loading via flags.

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);

`as_pool_add_metadata_location` has been deprecated since version 0.15.0 and should not be used in newly-written code.

Use `as_pool_add_extra_data_location` instead.

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

## Types and Values

### AS_TYPE_POOL

    #define AS_TYPE_POOL (as_pool_get_type ())

### struct AsPoolClass

    struct AsPoolClass {
    	GObjectClass parent_class;
    	void		(*changed) (AsPool *pool);
    };

### enum AsPoolFlags

Flags controlling the metadata pool behavior.

#### Members

AS_POOL_FLAG_NONE | No flags. |
AS_POOL_FLAG_LOAD_OS_CATALOG | Load AppStream catalog metadata from OS locations. |
AS_POOL_FLAG_LOAD_OS_METAINFO | Load MetaInfo data from OS locations. |
AS_POOL_FLAG_LOAD_OS_DESKTOP_FILES | Load components from desktop-entry files in OS locations. |
AS_POOL_FLAG_LOAD_FLATPAK | Load AppStream catalog metadata from Flatpak. |
AS_POOL_FLAG_IGNORE_CACHE_AGE | Load fresh data even if an up-o-date cache is available. |
AS_POOL_FLAG_RESOLVE_ADDONS | Always resolve addons for returned components. |
AS_POOL_FLAG_PREFER_OS_METAINFO | Prefer local metainfo data over the system-provided catalog data. Useful for debugging. |
AS_POOL_FLAG_MONITOR | Monitor registered directories for changes, and auto-reload metadata if necessary. |

### AS_POOL_FLAG_LOAD_OS_COLLECTION

    #define AS_POOL_FLAG_LOAD_OS_COLLECTION AS_POOL_FLAG_LOAD_OS_CATALOG

### AS_POOL_FLAG_READ_COLLECTION

    #define AS_POOL_FLAG_READ_COLLECTION AS_POOL_FLAG_LOAD_OS_CATALOG

### AS_POOL_FLAG_READ_METAINFO

    #define AS_POOL_FLAG_READ_METAINFO AS_POOL_FLAG_LOAD_OS_METAINFO

### AS_POOL_FLAG_READ_DESKTOP_FILES

    #define AS_POOL_FLAG_READ_DESKTOP_FILES AS_POOL_FLAG_LOAD_OS_DESKTOP_FILES

### 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 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;