gs-app-query: GNOME Software Reference Manual

## gs-app-query gs-app-query — Immutable representation of a query for apps |

## Functions

gboolean | gs_component_kind_array_contains ()
GsAppQuery * | gs_app_query_new ()
GsPluginRefineFlags | gs_app_query_get_refine_flags ()
GsPluginRefineRequireFlags | gs_app_query_get_refine_require_flags ()
guint | gs_app_query_get_max_results ()
GsAppListFilterFlags | gs_app_query_get_dedupe_flags ()
GsAppListSortFunc | gs_app_query_get_sort_func ()
GsAppListFilterFunc | gs_app_query_get_filter_func ()
guint | gs_app_query_get_n_properties_set ()
const gchar * const * | gs_app_query_get_provides_files ()
GDateTime * | gs_app_query_get_released_since ()
GsAppQueryTristate | gs_app_query_get_is_curated ()
GsAppQueryTristate | gs_app_query_get_is_featured ()
GsCategory * | gs_app_query_get_category ()
GsAppQueryTristate | gs_app_query_get_is_installed ()
const gchar * const * | gs_app_query_get_developers ()
const gchar * const * | gs_app_query_get_keywords ()
GsApp * | gs_app_query_get_alternate_of ()
GsAppQueryProvidesType | gs_app_query_get_provides ()
GsAppQueryLicenseType | gs_app_query_get_license_type ()
GsAppQueryDeveloperVerifiedType | gs_app_query_get_developer_verified_type ()
GsAppQueryTristate | gs_app_query_get_is_for_update ()
GsAppQueryTristate | gs_app_query_get_is_historical_update ()
const AsComponentKind * | gs_app_query_get_component_kinds ()
const gchar * | gs_app_query_get_is_langpack_for_locale ()

## Types and Values

enum | GsAppQueryTristate
enum | GsAppQueryProvidesType
enum | GsAppQueryLicenseType
enum | GsAppQueryDeveloperVerifiedType
#define | GS_APP_QUERY_DEDUPE_FLAGS_DEFAULT
#define | GS_TYPE_APP_QUERY
| GsAppQuery

## Description

GsAppQuery is an object to represent a query for apps.

It will typically be used with GsPluginJobListApps, which searches for matching apps, but it may have multiple consumers. GsAppQuery only represents the query and does not provide an implementation for executing that query.

It is immutable after construction, and hence threadsafe. It may be extended in future by adding more query properties. The existing query properties are conjunctive: results should only be returned which match *all* properties which are set, not _any_ properties which are set.

The set of apps returned for the query can be controlled with the “refine-flags”, “refine-require-flags”, “max-results” and “dedupe-flags” properties. If `refine-flags` is set, all results must be refined using the given set of refine flags (see GsPluginJobRefine). `max-results` and `dedupe-flags` are used to limit the set of results.

Results must always be processed in this order:

- Filtering using “filter-func” (and any other custom filter functions the query executor provides).

- Deduplication using “dedupe-flags”.

- Sorting using “sort-func”.

- Truncating result list length to “max-results”.

## Functions

### gs_component_kind_array_contains ()

    gboolean
    gs_component_kind_array_contains (const AsComponentKind *haystack,
                                      AsComponentKind needle);

Search for `needle` in `haystack` .

If `haystack` is `NULL`, that is treated as equivalent to it being an empty array.

#### Parameters

haystack | array of AsComponentKind values, terminated with a zero (`AS_COMPONENT_KIND_UNKNOWN`). | [nullable][array zero-terminated=1]
needle | component kind to search for in the array |

#### Returns

`TRUE` if `needle` is in `haystack` , `FALSE` otherwise

Since: 49

### gs_app_query_new ()

    GsAppQuery *
    gs_app_query_new (const gchar *first_property_name,
                      ...);

Create a new GsAppQuery containing the given query properties.

#### Parameters

first_property_name | name of the first GObject property |
... | value for the first property, followed by additional property/value pairs, then a terminating `NULL` |

#### Returns

a new GsAppQuery.

[transfer full]

Since: 43

### gs_app_query_get_refine_flags ()

    GsPluginRefineFlags
    gs_app_query_get_refine_flags (GsAppQuery *self);

Get the value of “refine-flags”.

#### Parameters

self | a GsAppQuery |

#### Returns

the refine flags for the query

Since: 49

### gs_app_query_get_refine_require_flags ()

    GsPluginRefineRequireFlags
    gs_app_query_get_refine_require_flags (GsAppQuery *self);

Get the value of “refine-require-flags”.

#### Parameters

self | a GsAppQuery |

#### Returns

the refine require flags for the query

Since: 49

### gs_app_query_get_max_results ()

    guint
    gs_app_query_get_max_results (GsAppQuery *self);

Get the value of “max-results”.

#### Parameters

self | a GsAppQuery |

#### Returns

the maximum number of results to return for the query, or `0` to indicate no limit

Since: 43

### gs_app_query_get_dedupe_flags ()

    GsAppListFilterFlags
    gs_app_query_get_dedupe_flags (GsAppQuery *self);

Get the value of “dedupe-flags”.

#### Parameters

self | a GsAppQuery |

#### Returns

the dedupe flags for the query

Since: 43

### gs_app_query_get_sort_func ()

    GsAppListSortFunc
    gs_app_query_get_sort_func (GsAppQuery *self,
                                gpointer *user_data_out);

Get the value of “sort-func”.

#### Parameters

self | a GsAppQuery |
user_data_out | return location for the “sort-user-data”, or `NULL` to ignore. | [out][transfer none][optional][nullable]

#### Returns

the sort function for the query.

[nullable]

Since: 43

### gs_app_query_get_filter_func ()

    GsAppListFilterFunc
    gs_app_query_get_filter_func (GsAppQuery *self,
                                  gpointer *user_data_out);

Get the value of “filter-func”.

#### Parameters

self | a GsAppQuery |
user_data_out | return location for the “filter-user-data”, or `NULL` to ignore. | [out][transfer none][optional][nullable]

#### Returns

the filter function for the query.

[nullable]

Since: 43

### gs_app_query_get_n_properties_set ()

    guint
    gs_app_query_get_n_properties_set (GsAppQuery *self);

Get the number of query properties which have been set.

These are the properties which determine the query results, rather than ones which control refining the results (“refine-flags”, “refine-require-flags”, “max-results”, “dedupe-flags”, “sort-func” and its user data, “filter-func” and its user data, “license-type”).

#### Parameters

self | a GsAppQuery |

#### Returns

number of properties set so they will affect query results

Since: 43

### gs_app_query_get_provides_files ()

    const gchar * const	*
    gs_app_query_get_provides_files (GsAppQuery *self);

Get the value of “provides-files”.

#### Parameters

self | a GsAppQuery |

#### Returns

a list of file paths which the apps must provide, or `NULL` to not filter on file paths.

[nullable]

Since: 43

### gs_app_query_get_released_since ()

    GDateTime *
    gs_app_query_get_released_since (GsAppQuery *self);

Get the value of “released-since”.

#### Parameters

self | a GsAppQuery |

#### Returns

a date/time which apps must have been released since, or `NULL` to not filter on release date.

[nullable]

Since: 43

### gs_app_query_get_is_curated ()

    GsAppQueryTristate
    gs_app_query_get_is_curated (GsAppQuery *self);

Get the value of “is-curated”.

#### Parameters

self | a GsAppQuery |

#### Returns

`GS_APP_QUERY_TRISTATE_TRUE` if apps must be curated, `GS_APP_QUERY_TRISTATE_FALSE` if they must be not curated, or `GS_APP_QUERY_TRISTATE_UNSET` if it doesn’t matter

Since: 43

### gs_app_query_get_is_featured ()

    GsAppQueryTristate
    gs_app_query_get_is_featured (GsAppQuery *self);

Get the value of “is-featured”.

#### Parameters

self | a GsAppQuery |

#### Returns

`GS_APP_QUERY_TRISTATE_TRUE` if apps must be featured, `GS_APP_QUERY_TRISTATE_FALSE` if they must be not featured, or `GS_APP_QUERY_TRISTATE_UNSET` if it doesn’t matter

Since: 43

### gs_app_query_get_category ()

    GsCategory *
    gs_app_query_get_category (GsAppQuery *self);

Get the value of “category”.

#### Parameters

self | a GsAppQuery |

#### Returns

a category which apps must be part of, or `NULL` to not filter on category.

[nullable][transfer none]

Since: 43

### gs_app_query_get_is_installed ()

    GsAppQueryTristate
    gs_app_query_get_is_installed (GsAppQuery *self);

Get the value of “is-installed”.

#### Parameters

self | a GsAppQuery |

#### Returns

`GS_APP_QUERY_TRISTATE_TRUE` if apps must be installed, `GS_APP_QUERY_TRISTATE_FALSE` if they must be not installed, or `GS_APP_QUERY_TRISTATE_UNSET` if it doesn’t matter

Since: 43

### gs_app_query_get_developers ()

    const gchar * const	*
    gs_app_query_get_developers (GsAppQuery *self);

Get the value of “developers”.

#### Parameters

self | a GsAppQuery |

#### Returns

a list of developers who provide the apps, or `NULL` to not filter by it.

[nullable]

Since: 43

### gs_app_query_get_keywords ()

    const gchar * const	*
    gs_app_query_get_keywords (GsAppQuery *self);

Get the value of “keywords”.

#### Parameters

self | a GsAppQuery |

#### Returns

a set of search keywords which apps must match, or `NULL` to not filter by it

Since: 43

### gs_app_query_get_alternate_of ()

    GsApp *
    gs_app_query_get_alternate_of (GsAppQuery *self);

Get the value of “alternate-of”.

#### Parameters

self | a GsAppQuery |

#### Returns

an app which apps must be related to, or `NULL` to not filter on alternates.

[nullable][transfer none]

Since: 43

### gs_app_query_get_provides ()

    GsAppQueryProvidesType
    gs_app_query_get_provides (GsAppQuery *self,
                               const gchar **out_provides_tag);

Get the value of “provides-type” and “provides-tag”.

#### Parameters

self | a GsAppQuery |
out_provides_tag | return location for the value of “provides-tag”, or `NULL` to ignore. | [transfer none][optional][nullable][out]

#### Returns

the type of tag to filter on, or `GS_APP_QUERY_PROVIDES_UNKNOWN` to not filter on provides

Since: 43

### gs_app_query_get_license_type ()

    GsAppQueryLicenseType
    gs_app_query_get_license_type (GsAppQuery *self);

Get the value of “license-type”.

#### Parameters

self | a GsAppQuery |

#### Returns

the type of license the app must be under, or `GS_APP_QUERY_LICENSE_ANY` to not filter by license

Since: 44

### gs_app_query_get_developer_verified_type ()

    GsAppQueryDeveloperVerifiedType
    gs_app_query_get_developer_verified_type
                                   (GsAppQuery *self);

Get the value of “developer-verified-type”.

#### Parameters

self | a GsAppQuery |

#### Returns

the type of developer verified state filter, or `GS_APP_QUERY_DEVELOPER_VERIFIED_ANY` to not filter by it

Since: 46

### gs_app_query_get_is_for_update ()

    GsAppQueryTristate
    gs_app_query_get_is_for_update (GsAppQuery *self);

Get the value of “is-for-update”.

#### Parameters

self | a GsAppQuery |

#### Returns

`GS_APP_QUERY_TRISTATE_TRUE` if query is only for apps which can be updated, `GS_APP_QUERY_TRISTATE_FALSE` if query is only for apps which cannot be updated, or `GS_APP_QUERY_TRISTATE_UNSET` if it doesn’t matter

Since: 47

### gs_app_query_get_is_historical_update ()

    GsAppQueryTristate
    gs_app_query_get_is_historical_update (GsAppQuery *self);

Get the value of “is-historical-update”.

#### Parameters

self | a GsAppQuery |

#### Returns

`GS_APP_QUERY_TRISTATE_TRUE` if query is only for apps which had been recently updated, `GS_APP_QUERY_TRISTATE_FALSE` if query is only for apps which had not been recently updated, or `GS_APP_QUERY_TRISTATE_UNSET` if it doesn’t matter

Since: 47

### gs_app_query_get_component_kinds ()

    const AsComponentKind *
    gs_app_query_get_component_kinds (GsAppQuery *self);

Get the value of “component-kinds”.

#### Parameters

self | a GsAppQuery |

#### Returns

a set of component kinds which apps must match one of, or `NULL` to not filter by it

Since: 49

### gs_app_query_get_is_langpack_for_locale ()

    const gchar *
    gs_app_query_get_is_langpack_for_locale
                                   (GsAppQuery *self);

Get the value of “is-langpack-for-locale”.

#### Parameters

self | a GsAppQuery |

#### Returns

a locale to filter for langpacks with, or `NULL` to not filter.

[nullable]

Since: 49

## Types and Values

### enum GsAppQueryTristate

A type for storing a boolean value which can also have an ‘unknown’ or ‘unset’ state.

Within GsAppQuery this is used for boolean query properties which are unset by default so that they don’t affect the query.

#### Members

GS_APP_QUERY_TRISTATE_UNSET | Value is unset. |
GS_APP_QUERY_TRISTATE_FALSE | False. Equal in value to `FALSE`. |
GS_APP_QUERY_TRISTATE_TRUE | True. Equal in value to `TRUE`. |

Since: 43

### enum GsAppQueryProvidesType

A type for identifying the format or meaning of “provides-tag”.

This allows querying for apps which provide various types of functionality, such as printer drivers or fonts.

#### Members

GS_APP_QUERY_PROVIDES_UNKNOWN | Format is unknown and value is unset. |
GS_APP_QUERY_PROVIDES_PACKAGE_NAME | A package name in whatever ID format is used natively by the current distro. |
GS_APP_QUERY_PROVIDES_GSTREAMER | A GStreamer plugin name which the app must provide. |
GS_APP_QUERY_PROVIDES_FONT | A font name which the app must provide. |
GS_APP_QUERY_PROVIDES_MIME_HANDLER | A MIME type/content type which the app must support. |
GS_APP_QUERY_PROVIDES_PS_DRIVER | A printer/PostScript driver which the app must provide. |
GS_APP_QUERY_PROVIDES_PLASMA | A Plasma ID which the app must provide. (FIXME: It’s not really clear what this means, but it’s historically been supported.) |

Since: 43

### enum GsAppQueryLicenseType

A type for categorising licenses, so that apps can be filtered by the type of license they have.

#### Members

GS_APP_QUERY_LICENSE_ANY | Any license, proprietary or free |
GS_APP_QUERY_LICENSE_FOSS | Only free licenses (FOSS or open source) |

Since: 44

### enum GsAppQueryDeveloperVerifiedType

A type to filter apps by developer verified identity.

#### Members

GS_APP_QUERY_DEVELOPER_VERIFIED_ANY | Any app, with or without verified developer identity |
GS_APP_QUERY_DEVELOPER_VERIFIED_ONLY | Only apps with verified developer identity |

Since: 46

### GS_APP_QUERY_DEDUPE_FLAGS_DEFAULT

    #define             GS_APP_QUERY_DEDUPE_FLAGS_DEFAULT

Common default value to use for “dedupe-flags”.

This is not set as the default for all GsAppQuery instances, but is a typical value which callers might want to specify themselves.

It deduplicates by ID, default source and version.

Since: 49

### GS_TYPE_APP_QUERY

    #define GS_TYPE_APP_QUERY (gs_app_query_get_type ())

### GsAppQuery

    typedef struct _GsAppQuery GsAppQuery;