## 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 ()
gboolean | as_pool_load_cache_file ()
gboolean | as_pool_save_cache_file ()
void | as_pool_clear ()
gboolean | as_pool_add_component ()
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_search ()
void | as_pool_clear_metadata_locations ()
void | as_pool_add_metadata_location ()
AsCacheFlags | as_pool_get_cache_flags ()
void | as_pool_set_cache_flags ()
AsPoolFlags | as_pool_get_flags ()
void | as_pool_set_flags ()
gboolean | as_pool_refresh_cache ()

## Types and Values

#define | AS_TYPE_POOL
struct | AsPoolClass
enum | AsCacheFlags
enum | AsPoolFlags
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 pazhs 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 farious criteria, and also add new metadata to the pool. The caching behavior can be controlled by the application using AsPool.

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

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. |
error | A GError or `NULL`. |

#### Returns

`TRUE` if update completed without error.

### as_pool_load_cache_file ()

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

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

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

    void
    as_pool_clear (AsPool *pool);

Remove all metadat from the pool.

#### 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 full][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 full][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 full][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 full][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 full][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 full][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 terms. 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_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_refresh_cache ()

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

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.

## 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 global metadata cache. |

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

    #define AS_POOL_ERROR as_pool_error_quark ()

### AsPool

    typedef struct _AsPool AsPool;