libflatpak API Reference<a class="headerlink" href="#libflatpak-api-reference" title="Permalink to this headline">¶

[transfer full]

flatpak_installation_new_system_with_id ()

FlatpakInstallation *
flatpak_installation_new_system_with_id
                               (const char *id,
                                GCancellable *cancellable,
                                GError **error);

Creates a new FlatpakInstallation for the system-wide installation id .

Parameters

id	the ID of the system-wide installation.	[nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

[transfer full]

Since: 0.8

flatpak_installation_new_user ()

FlatpakInstallation *
flatpak_installation_new_user (GCancellable *cancellable,
                               GError **error);

Creates a new FlatpakInstallation for the per-user installation.

Parameters

cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

[transfer full]

flatpak_installation_new_for_path ()

FlatpakInstallation *
flatpak_installation_new_for_path (GFile *path,
                                   gboolean user,
                                   GCancellable *cancellable,
                                   GError **error);

Creates a new FlatpakInstallation for the installation at the given path .

Parameters

path	a GFile
user	whether this is a user-specific location
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

[transfer full]

flatpak_installation_get_is_user ()

gboolean
flatpak_installation_get_is_user (FlatpakInstallation *self);

Returns whether the installation is for a user-specific location.

Parameters

self

Returns

TRUE if self is a per-user installation

flatpak_installation_get_path ()

GFile *
flatpak_installation_get_path (FlatpakInstallation *self);

Returns the installation location for self .

Parameters

self

Returns

an GFile.

[transfer full]

flatpak_installation_create_monitor ()

GFileMonitor *
flatpak_installation_create_monitor (FlatpakInstallation *self,
                                     GCancellable *cancellable,
                                     GError **error);

Gets monitor object for the installation. The returned file monitor will emit the “changed” signal whenever an application or runtime was installed, uninstalled or updated.

Parameters

self	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a new GFileMonitor instance, or NULL on error.

[transfer full]

flatpak_installation_install ()

FlatpakInstalledRef *
flatpak_installation_install (FlatpakInstallation *self,
                              const char *remote_name,
                              FlatpakRefKind kind,
                              const char *name,
                              const char *arch,
                              const char *branch,
                              FlatpakProgressCallback progress,
                              gpointer progress_data,
                              GCancellable *cancellable,
                              GError **error);

Install a new application or runtime.

Note that this function was originally written to always return a FlatpakInstalledRef. Since 0.9.13, passing FLATPAK_INSTALL_FLAGS_NO_DEPLOY will only pull refs into the local flatpak repository without deploying them, however this function will be unable to provide information on the installed ref, so FLATPAK_ERROR_ONLY_PULLED will be set and the caller must respond accordingly.

Parameters

self	a FlatpakInstallation
remote_name	name of the remote to use
kind	what this ref contains (an FlatpakRefKind)
name	name of the app/runtime to fetch
arch	which architecture to fetch (default: current architecture).	[nullable]
branch	which branch to fetch (default: 'master').	[nullable]
progress	progress callback.	[scope call][nullable]
progress_data	user data passed to `progress` .	[closure progress][nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

The ref for the newly installed app or NULL on failure.

[transfer full]

flatpak_installation_install_full ()

FlatpakInstalledRef *
flatpak_installation_install_full (FlatpakInstallation *self,
                                   FlatpakInstallFlags flags,
                                   const char *remote_name,
                                   FlatpakRefKind kind,
                                   const char *name,
                                   const char *arch,
                                   const char *branch,
                                   const char * const *subpaths,
                                   FlatpakProgressCallback progress,
                                   gpointer progress_data,
                                   GCancellable *cancellable,
                                   GError **error);

Install a new application or runtime.

Note that this function was originally written to always return a FlatpakInstalledRef. Since 0.9.13, passing FLATPAK_INSTALL_FLAGS_NO_DEPLOY will only pull refs into the local flatpak repository without deploying them, however this function will be unable to provide information on the installed ref, so FLATPAK_ERROR_ONLY_PULLED will be set and the caller must respond accordingly.

Parameters

self	a FlatpakInstallation
flags	set of FlatpakInstallFlags flag
remote_name	name of the remote to use
kind	what this ref contains (an FlatpakRefKind)
name	name of the app/runtime to fetch
arch	which architecture to fetch (default: current architecture).	[nullable]
branch	which branch to fetch (default: 'master').	[nullable]
subpaths	A list of subpaths to fetch, or `NULL` for everything.	[nullable][array zero-terminated=1]
progress	progress callback.	[scope call][nullable]
progress_data	user data passed to `progress` .	[closure progress][nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

The ref for the newly installed app or NULL on failure.

[transfer full]

flatpak_installation_update ()

FlatpakInstalledRef *
flatpak_installation_update (FlatpakInstallation *self,
                             FlatpakUpdateFlags flags,
                             FlatpakRefKind kind,
                             const char *name,
                             const char *arch,
                             const char *branch,
                             FlatpakProgressCallback progress,
                             gpointer progress_data,
                             GCancellable *cancellable,
                             GError **error);

Update an application or runtime.

If the specified package is not installed, then FLATPAK_ERROR_NOT_INSTALLED will be thrown.

If no updates could be found on the remote end and the package is already up to date, then FLATPAK_ERROR_ALREADY_INSTALLED will be thrown.

Parameters

self	a FlatpakInstallation
flags	set of FlatpakUpdateFlags flag
kind	whether this is an app or runtime
name	name of the app or runtime to update
arch	architecture of the app or runtime to update (default: current architecture).	[nullable]
branch	name of the branch of the app or runtime to update (default: master).	[nullable]
progress	the callback.	[scope call][nullable]
progress_data	user data passed to `progress` .	[closure progress][nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

The ref for the newly updated app or NULL on failure.

[transfer full]

flatpak_installation_update_full ()

FlatpakInstalledRef *
flatpak_installation_update_full (FlatpakInstallation *self,
                                  FlatpakUpdateFlags flags,
                                  FlatpakRefKind kind,
                                  const char *name,
                                  const char *arch,
                                  const char *branch,
                                  const char * const *subpaths,
                                  FlatpakProgressCallback progress,
                                  gpointer progress_data,
                                  GCancellable *cancellable,
                                  GError **error);

Update an application or runtime.

If the specified package is not installed, then FLATPAK_ERROR_NOT_INSTALLED will be thrown.

If no updates could be found on the remote end and the package is already up to date, then FLATPAK_ERROR_ALREADY_INSTALLED will be thrown.

Parameters

self	a FlatpakInstallation
flags	set of FlatpakUpdateFlags flag
kind	whether this is an app or runtime
name	name of the app or runtime to update
arch	architecture of the app or runtime to update (default: current architecture).	[nullable]
branch	name of the branch of the app or runtime to update (default: master).	[nullable]
subpaths	A list of subpaths to fetch, or `NULL` for everything.	[nullable][array zero-terminated=1]
progress	the callback.	[scope call][nullable]
progress_data	user data passed to `progress` .	[closure progress][nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

The ref for the newly updated app or NULL on failure.

[transfer full]

flatpak_installation_uninstall ()

gboolean
flatpak_installation_uninstall (FlatpakInstallation *self,
                                FlatpakRefKind kind,
                                const char *name,
                                const char *arch,
                                const char *branch,
                                FlatpakProgressCallback progress,
                                gpointer progress_data,
                                GCancellable *cancellable,
                                GError **error);

Uninstall an application or runtime.

Parameters

self	a FlatpakInstallation
kind	what this ref contains (an FlatpakRefKind)
name	name of the app or runtime to uninstall
arch	architecture of the app or runtime to uninstall; if `NULL`, `flatpak_get_default_arch()` is assumed.	[nullable]
branch	name of the branch of the app or runtime to uninstall; if `NULL`, `master` is assumed.	[nullable]
progress	the callback.	[scope call][nullable]
progress_data	user data passed to `progress` .	[closure progress][nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE on success

flatpak_installation_uninstall_full ()

gboolean
flatpak_installation_uninstall_full (FlatpakInstallation *self,
                                     FlatpakUninstallFlags flags,
                                     FlatpakRefKind kind,
                                     const char *name,
                                     const char *arch,
                                     const char *branch,
                                     FlatpakProgressCallback progress,
                                     gpointer progress_data,
                                     GCancellable *cancellable,
                                     GError **error);

Uninstall an application or runtime.

Parameters

self	a FlatpakInstallation
flags	set of FlatpakUninstallFlags flags
kind	what this ref contains (an FlatpakRefKind)
name	name of the app or runtime to uninstall
arch	architecture of the app or runtime to uninstall; if `NULL`, `flatpak_get_default_arch()` is assumed.	[nullable]
branch	name of the branch of the app or runtime to uninstall; if `NULL`, `master` is assumed.	[nullable]
progress	the callback.	[scope call][nullable]
progress_data	user data passed to `progress` .	[closure progress][nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE on success

Since: 0.11.8

flatpak_installation_launch ()

gboolean
flatpak_installation_launch (FlatpakInstallation *self,
                             const char *name,
                             const char *arch,
                             const char *branch,
                             const char *commit,
                             GCancellable *cancellable,
                             GError **error);

Launch an installed application.

You can use flatpak_installation_get_installed_ref() or flatpak_installation_get_current_installed_app() to find out what builds are available, in order to get a value for commit .

Parameters

self	a FlatpakInstallation
name	name of the app to launch
arch	which architecture to launch (default: current architecture).	[nullable]
branch	which branch of the application (default: "master").	[nullable]
commit	the commit of `branch` to launch.	[nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE, unless an error occurred

flatpak_installation_launch_full ()

gboolean
flatpak_installation_launch_full (FlatpakInstallation *self,
                                  FlatpakLaunchFlags flags,
                                  const char *name,
                                  const char *arch,
                                  const char *branch,
                                  const char *commit,
                                  FlatpakInstance **instance_out,
                                  GCancellable *cancellable,
                                  GError **error);

Launch an installed application.

You can use flatpak_installation_get_installed_ref() or flatpak_installation_get_current_installed_app() to find out what builds are available, in order to get a value for commit .

Compared to flatpak_installation_launch(), this function returns a FlatpakInstance that can be used to get information about the running instance. You can also use it to wait for the instance to be done with g_child_watch_add() if you pass the FLATPAK_LAUNCH_FLAGS_DO_NOT_REAP flag.

Parameters

self	a FlatpakInstallation
flags	set of FlatpakLaunchFlags
name	name of the app to launch
arch	which architecture to launch (default: current architecture).	[nullable]
branch	which branch of the application (default: "master").	[nullable]
commit	the commit of `branch` to launch.	[nullable]
instance_out	return location for a FlatpakInstance.	[nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE, unless an error occurred

Since: 1.1

flatpak_installation_get_current_installed_app ()

FlatpakInstalledRef *
flatpak_installation_get_current_installed_app
                               (FlatpakInstallation *self,
                                const char *name,
                                GCancellable *cancellable,
                                GError **error);

Get the last build of reference name that was installed with flatpak_installation_install(), or NULL if the reference has never been installed locally.

Parameters

self	a FlatpakInstallation
name	the name of the app
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

an FlatpakInstalledRef.

[transfer full]

flatpak_installation_get_display_name ()

const char *
flatpak_installation_get_display_name (FlatpakInstallation *self);

Returns the display name of the installation for self .

Parameters

self

Returns

a string with the installation's display name.

[transfer none]

Since: 0.8

flatpak_installation_get_id ()

const char *
flatpak_installation_get_id (FlatpakInstallation *self);

Returns the ID of the installation for self .

Parameters

self

Returns

a string with the installation's ID.

[transfer none]

Since: 0.8

flatpak_installation_get_installed_ref ()

FlatpakInstalledRef *
flatpak_installation_get_installed_ref
                               (FlatpakInstallation *self,
                                FlatpakRefKind kind,
                                const char *name,
                                const char *arch,
                                const char *branch,
                                GCancellable *cancellable,
                                GError **error);

Returns information about an installed ref, such as the available builds, its size, location, etc.

Parameters

self	a FlatpakInstallation
kind	whether this is an app or runtime
name	name of the app/runtime to fetch
arch	which architecture to fetch (default: current architecture).	[nullable]
branch	which branch to fetch (default: "master").	[nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

an FlatpakInstalledRef, or NULL if an error occurred.

[transfer full]

flatpak_installation_get_min_free_space_bytes ()

gboolean
flatpak_installation_get_min_free_space_bytes
                               (FlatpakInstallation *self,
                                guint64 *out_bytes,
                                GError **error);

Returns the min-free-space config value from the OSTree repository of this installation.

Applications can use this value, together with information about the available disk space and the size of pending updates or installs, to estimate whether a pull operation will fail due to running out of disk space.

Parameters

self	a FlatpakInstallation
out_bytes	Location to store the result.	[out]
error	Return location for a GError

Returns

TRUE on success, or FALSE on error.

Since: 1.1

flatpak_installation_get_priority ()

gint
flatpak_installation_get_priority (FlatpakInstallation *self);

Returns the numeric priority of the installation for self .

Parameters

self

Returns

an integer with the configured priority value

Since: 0.8

flatpak_installation_get_storage_type ()

FlatpakStorageType
flatpak_installation_get_storage_type (FlatpakInstallation *self);

Returns the type of storage of the installation for self .

Parameters

self

Returns

a FlatpakStorageType

Since: 0.8

flatpak_installation_list_installed_refs ()

GPtrArray *
flatpak_installation_list_installed_refs
                               (FlatpakInstallation *self,
                                GCancellable *cancellable,
                                GError **error);

Lists the installed references.

Parameters

self	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a GPtrArray of FlatpakInstalledRef instances.

[transfer container][element-type FlatpakInstalledRef]

flatpak_installation_list_installed_refs_by_kind ()

GPtrArray *
flatpak_installation_list_installed_refs_by_kind
                               (FlatpakInstallation *self,
                                FlatpakRefKind kind,
                                GCancellable *cancellable,
                                GError **error);

Lists the installed references of a specific kind.

Parameters

self	a FlatpakInstallation
kind	the kind of installation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a GPtrArray of FlatpakInstalledRef instances.

[transfer container][element-type FlatpakInstalledRef]

flatpak_installation_list_installed_refs_for_update ()

GPtrArray *
flatpak_installation_list_installed_refs_for_update
                               (FlatpakInstallation *self,
                                GCancellable *cancellable,
                                GError **error);

Lists the installed references that has a remote update that is not locally available. However, even though an app is not returned by this it can have local updates available that has not been deployed. Look at commit vs latest_commit on installed apps for this.

Parameters

self	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a GPtrArray of FlatpakInstalledRef instances, or NULL on error.

[transfer container][element-type FlatpakInstalledRef]

flatpak_installation_list_installed_related_refs_sync ()

GPtrArray *
flatpak_installation_list_installed_related_refs_sync
                               (FlatpakInstallation *self,
                                const char *remote_name,
                                const char *ref,
                                GCancellable *cancellable,
                                GError **error);

Lists all the locally installed refs from remote_name that are related to ref . These are things that are interesting to install, update, or uninstall together with ref . For instance, locale data or debug information.

This function is similar to flatpak_installation_list_remote_related_refs_sync, but instead of looking at what is available on the remote, it only looks at the locally installed refs. This is useful for instance when you're looking for related refs to uninstall, or when you're planning to use FLATPAK_UPDATE_FLAGS_NO_PULL to install previously pulled refs.

Parameters

self	a FlatpakInstallation
remote_name	the name of the remote
ref	the ref
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a GPtrArray of FlatpakRelatedRef instances.

[transfer container][element-type FlatpakRelatedRef]

Since: 0.6.7

flatpak_installation_list_remote_refs_sync ()

GPtrArray *
flatpak_installation_list_remote_refs_sync
                               (FlatpakInstallation *self,
                                const char *remote_or_uri,
                                GCancellable *cancellable,
                                GError **error);

Lists all the applications and runtimes in a remote.

Parameters

self	a FlatpakInstallation
remote_or_uri	the name or URI of the remote
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a GPtrArray of FlatpakRemoteRef instances.

[transfer container][element-type FlatpakRemoteRef]

flatpak_installation_list_remotes_by_type ()

GPtrArray *
flatpak_installation_list_remotes_by_type
                               (FlatpakInstallation *self,
                                const FlatpakRemoteType types[],
                                gsize num_types,
                                GCancellable *cancellable,
                                GError **error);

Lists only the remotes whose type is included in the types argument.

Parameters

self	a FlatpakInstallation
types	an array of FlatpakRemoteType.	[array length=num_types]
num_types	the number of types provided in `types`
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a GPtrArray of FlatpakRemote instances.

[transfer container][element-type FlatpakRemote]

flatpak_installation_list_remote_related_refs_sync ()

GPtrArray *
flatpak_installation_list_remote_related_refs_sync
                               (FlatpakInstallation *self,
                                const char *remote_name,
                                const char *ref,
                                GCancellable *cancellable,
                                GError **error);

Lists all the available refs on remote_name that are related to ref , and the subpaths to use. These are things that are interesting to install, update, or uninstall together with ref . For instance, locale data or debug information.

The returned list contains all available related refs, but not everyone should always be installed. For example, flatpak_related_ref_should_download() returns TRUE if the reference should be installed/updated with the app, and flatpak_related_ref_should_delete() returns TRUE if it should be uninstalled with the main ref.

The commit property of each FlatpakRelatedRef is not guaranteed to be non-NULL.

Parameters

self	a FlatpakInstallation
remote_name	the name of the remote
ref	the ref
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a GPtrArray of FlatpakRelatedRef instances.

[transfer container][element-type FlatpakRelatedRef]

Since: 0.6.7

flatpak_installation_list_remotes ()

GPtrArray *
flatpak_installation_list_remotes (FlatpakInstallation *self,
                                   GCancellable *cancellable,
                                   GError **error);

Lists the static remotes, in priority (highest first) order. For same priority, an earlier added remote comes before a later added one.

Parameters

self	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

an GPtrArray of FlatpakRemote instances.

[transfer container][element-type FlatpakRemote]

flatpak_installation_get_remote_by_name ()

FlatpakRemote *
flatpak_installation_get_remote_by_name
                               (FlatpakInstallation *self,
                                const gchar *name,
                                GCancellable *cancellable,
                                GError **error);

Looks up a remote by name.

Parameters

self	a FlatpakInstallation
name	a remote name
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a FlatpakRemote instances, or NULL error.

[transfer full]

flatpak_installation_fetch_remote_metadata_sync ()

GBytes *
flatpak_installation_fetch_remote_metadata_sync
                               (FlatpakInstallation *self,
                                const char *remote_name,
                                FlatpakRef *ref,
                                GCancellable *cancellable,
                                GError **error);

Obtains the metadata file from a commit.

NOTE: Since 0.11.4 this information is accessible in FlatpakRemoteRef, so this function is not very useful anymore.

Parameters

self	a FlatpakInstallation
remote_name	the name of the remote
ref	the ref
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a GBytes containing the flatpak metadata file, or NULL if an error occurred.

[transfer full]

flatpak_installation_fetch_remote_ref_sync ()

FlatpakRemoteRef *
flatpak_installation_fetch_remote_ref_sync
                               (FlatpakInstallation *self,
                                const char *remote_name,
                                FlatpakRefKind kind,
                                const char *name,
                                const char *arch,
                                const char *branch,
                                GCancellable *cancellable,
                                GError **error);

Gets the current remote branch of a ref in the remote.

Parameters

self	a FlatpakInstallation
remote_name	the name of the remote
kind	what this ref contains (an FlatpakRefKind)
name	name of the app/runtime to fetch
arch	which architecture to fetch (default: current architecture).	[nullable]
branch	which branch to fetch (default: 'master').	[nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a FlatpakRemoteRef instance, or NULL.

[transfer full]

flatpak_installation_fetch_remote_size_sync ()

gboolean
flatpak_installation_fetch_remote_size_sync
                               (FlatpakInstallation *self,
                                const char *remote_name,
                                FlatpakRef *ref,
                                guint64 *download_size,
                                guint64 *installed_size,
                                GCancellable *cancellable,
                                GError **error);

Gets information about the maximum amount of data that needs to be transferred to pull the ref from a remote repository, and about the amount of local disk space that is required to check out this commit.

Note that if there are locally available data that are in the ref, which is common for instance if you're doing an update then the real download size may be smaller than what is returned here.

NOTE: Since 0.11.4 this information is accessible in FlatpakRemoteRef, so this function is not very useful anymore.

Parameters

self	a FlatpakInstallation
remote_name	the name of the remote
ref	the ref
download_size	return location for the (maximum) download size.	[out]
installed_size	return location for the installed size.	[out]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE, unless an error occurred

flatpak_installation_load_app_overrides ()

char *
flatpak_installation_load_app_overrides
                               (FlatpakInstallation *self,
                                const char *app_id,
                                GCancellable *cancellable,
                                GError **error);

Loads the metadata overrides file for an application.

Parameters

self	a FlatpakInstallation
app_id	an application id
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

the contents of the overrides files, or NULL if an error occurred.

[transfer full]

flatpak_installation_update_appstream_sync ()

gboolean
flatpak_installation_update_appstream_sync
                               (FlatpakInstallation *self,
                                const char *remote_name,
                                const char *arch,
                                gboolean *out_changed,
                                GCancellable *cancellable,
                                GError **error);

Updates the local copy of appstream for remote_name for the specified arch . If you need progress feedback, use flatpak_installation_update_appstream_full_sync().

Parameters

self	a FlatpakInstallation
remote_name	the name of the remote
arch	Architecture to update, or `NULL` for the local machine arch
out_changed	Set to `TRUE` if the contents of the appstream changed, `FALSE` if nothing changed.	[nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE on success, or FALSE on error

flatpak_installation_install_bundle ()

FlatpakInstalledRef *
flatpak_installation_install_bundle (FlatpakInstallation *self,
                                     GFile *file,
                                     FlatpakProgressCallback progress,
                                     gpointer progress_data,
                                     GCancellable *cancellable,
                                     GError **error);

Install an application or runtime from an flatpak bundle file. See flatpak-build-bundle(1) for how to create bundles.

Parameters

self	a FlatpakInstallation
file	a GFile that is an flatpak bundle
progress	progress callback.	[scope call][nullable]
progress_data	user data passed to `progress` .	[closure progress][nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

The ref for the newly installed app or NULL on failure.

[transfer full]

flatpak_installation_install_ref_file ()

FlatpakRemoteRef *
flatpak_installation_install_ref_file (FlatpakInstallation *self,
                                       GBytes *ref_file_data,
                                       GCancellable *cancellable,
                                       GError **error);

Creates a remote based on the passed in .flatpakref file contents in ref_file_data and returns the FlatpakRemoteRef that can be used to install it.

Note, the FlatpakRemoteRef will not have the commit field set, or other details, to avoid unnecessary roundtrips. If you need that you have to resolve it explicitly with flatpak_installation_fetch_remote_ref_sync().

Parameters

self	a FlatpakInstallation
ref_file_data	The ref file contents
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a FlatpakRemoteRef if the remote has been added successfully, NULL on error.

[transfer full]

Since: 0.6.10

flatpak_installation_drop_caches ()

gboolean
flatpak_installation_drop_caches (FlatpakInstallation *self,
                                  GCancellable *cancellable,
                                  GError **error);

Drops all internal (in-memory) caches. For instance, this may be needed to pick up new or changed remotes configured outside this installation instance.

Parameters

self	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE on success, FALSE on error

flatpak_installation_modify_remote ()

gboolean
flatpak_installation_modify_remote (FlatpakInstallation *self,
                                    FlatpakRemote *remote,
                                    GCancellable *cancellable,
                                    GError **error);

Saves changes in the remote object.

Parameters

self	a FlatpakInstallation
remote	the modified FlatpakRemote
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE if the modifications have been committed successfully

flatpak_installation_remove_remote ()

gboolean
flatpak_installation_remove_remote (FlatpakInstallation *self,
                                    const char *name,
                                    GCancellable *cancellable,
                                    GError **error);

Removes the remote with the given name from the installation.

Parameters

self	a FlatpakInstallation
name	the name of the remote to remove
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE if the remote has been removed successfully

flatpak_installation_update_remote_sync ()

gboolean
flatpak_installation_update_remote_sync
                               (FlatpakInstallation *self,
                                const char *name,
                                GCancellable *cancellable,
                                GError **error);

Updates the local configuration of a remote repository by fetching the related information from the summary file in the remote OSTree repository and committing the changes to the local installation.

Parameters

self	a FlatpakInstallation
name	the name of the remote to update
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE if the remote has been updated successfully

Since: 0.6.13

flatpak_installation_cleanup_local_refs_sync ()

gboolean
flatpak_installation_cleanup_local_refs_sync
                               (FlatpakInstallation *self,
                                GCancellable *cancellable,
                                GError **error);

Remove all OSTree refs from the local flatpak repository which are not in a deployed state. The next time the underlying OSTree repo is pruned, objects which were attached to that ref will be removed. This is useful if you pulled a flatpak refs using flatpak_installation_install_full() and specified FLATPAK_INSTALL_FLAGS_NO_DEPLOY but then decided not to deploy the refs later on and want to remove the local refs to prevent them from taking up disk space. Note that this will not remove the objects referred to by ref from the underlying OSTree repo, you should use flatpak_installation_prune_local_repo() to do that.

Parameters

self	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE on success

Since: 0.10.0

flatpak_installation_get_config ()

char *
flatpak_installation_get_config (FlatpakInstallation *self,
                                 const char *key,
                                 GCancellable *cancellable,
                                 GError **error);

Get a global configuration option for the installation, see flatpak_installation_set_config_sync() for supported keys.

Parameters

self	a FlatpakInstallation
key	the name of the key to get
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

The (newly allocated) value, or NULL on error (G_KEY_FILE_ERROR_KEY_NOT_FOUND error if key is not set)

flatpak_installation_prune_local_repo ()

gboolean
flatpak_installation_prune_local_repo (FlatpakInstallation *self,
                                       GCancellable *cancellable,
                                       GError **error);

Remove all orphaned OSTree objects from the underlying OSTree repo in self .

Parameters

self	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE on success

Since: 0.10.0

flatpak_installation_remove_local_ref_sync ()

gboolean
flatpak_installation_remove_local_ref_sync
                               (FlatpakInstallation *self,
                                const char *remote_name,
                                const char *ref,
                                GCancellable *cancellable,
                                GError **error);

Remove the OSTree ref given by remote_name :ref from the local flatpak repository. The next time the underlying OSTree repo is pruned, objects which were attached to that ref will be removed. This is useful if you pulled a flatpak ref using flatpak_installation_install_full() and specified FLATPAK_INSTALL_FLAGS_NO_DEPLOY but then decided not to deploy the ref later on and want to remove the local ref to prevent it from taking up disk space. Note that this will not remove the objects referred to by ref from the underlying OSTree repo, you should use flatpak_installation_prune_local_repo() to do that.

Parameters

self	a FlatpakInstallation
remote_name	the name of the remote
ref	the ref
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE on success

Since: 0.10.0

flatpak_installation_set_config_sync ()

gboolean
flatpak_installation_set_config_sync (FlatpakInstallation *self,
                                      const char *key,
                                      const char *value,
                                      GCancellable *cancellable,
                                      GError **error);

Set a global configuration option for the installation, currently the only supported key is "languages", which is a comman-separated list of langue codes like "sv;en;pl", or "" to mean all languages.

Parameters

self	a FlatpakInstallation
key	the name of the key to set
value	the new value, or `NULL` to unset
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE if the option was set correctly

flatpak_installation_update_appstream_full_sync ()

gboolean
flatpak_installation_update_appstream_full_sync
                               (FlatpakInstallation *self,
                                const char *remote_name,
                                const char *arch,
                                FlatpakProgressCallback progress,
                                gpointer progress_data,
                                gboolean *out_changed,
                                GCancellable *cancellable,
                                GError **error);

Updates the local copy of appstream for remote_name for the specified arch .

Parameters

self	a FlatpakInstallation
remote_name	the name of the remote
arch	Architecture to update, or `NULL` for the local machine arch
progress	progress callback.	[scope call][nullable]
progress_data	user data passed to `progress` .	[closure progress][nullable]
out_changed	Set to `TRUE` if the contents of the appstream changed, `FALSE` if nothing changed.	[nullable]
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE on success, or FALSE on error

flatpak_installation_run_triggers ()

gboolean
flatpak_installation_run_triggers (FlatpakInstallation *self,
                                   GCancellable *cancellable,
                                   GError **error);

Run the trigger commands to update the files exported by the apps in self . Should be used after one or more app install, upgrade or uninstall operations with the FLATPAK_INSTALL_FLAGS_NO_TRIGGERS, FLATPAK_UPDATE_FLAGS_NO_TRIGGERS or FLATPAK_UNINSTALL_FLAGS_NO_TRIGGERS flags set.

Parameters

self	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

TRUE on success

Since: 1.0.3

flatpak_get_default_arch ()

const char *
flatpak_get_default_arch (void);

Returns the canonical name for the arch of the current machine.

Returns

an arch string

flatpak_get_supported_arches ()

const char *const *
flatpak_get_supported_arches (void);

Returns the canonical names for the arches that are supported (i.e. can run) on the current machine, in order of priority (default is first).

Returns

a zero terminated array of arch strings

flatpak_get_system_installations ()

GPtrArray *
flatpak_get_system_installations (GCancellable *cancellable,
                                  GError **error);

Lists the system installations according to the current configuration and current availability (e.g. doesn't return a configured installation if not reachable).

Parameters

cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a GPtrArray of FlatpakInstallation instances.

[transfer container][element-type FlatpakInstallation]

Since: 0.8

FlatpakProgressCallback ()

void
(*FlatpakProgressCallback) (const char *status,
                            guint progress,
                            gboolean estimating,
                            gpointer user_data);

The progress callback is called repeatedly during long-running operations such as installations or updates, and can be used to update progress information in a user interface.

The callback occurs in the thread-default context of the caller.

Parameters

status	A status string, suitable for display
progress	percentage of completion
estimating	whether `progress` is just an estimate
user_data	User data passed to the caller

Types and Values

struct FlatpakInstallation

struct FlatpakInstallation;

enum FlatpakUpdateFlags

Flags to alter the behavior of flatpak_installation_update().

Members

FLATPAK_UPDATE_FLAGS_NONE	Fetch remote builds and install the latest one (default)
FLATPAK_UPDATE_FLAGS_NO_DEPLOY	Don't install any new builds that might be fetched
FLATPAK_UPDATE_FLAGS_NO_PULL	Don't try to fetch new builds from the remote repo
FLATPAK_UPDATE_FLAGS_NO_STATIC_DELTAS	Don't use static deltas when pulling
FLATPAK_UPDATE_FLAGS_NO_PRUNE	Don't prune the local OSTree repository after updating (Since: 0.11.8)
FLATPAK_UPDATE_FLAGS_NO_TRIGGERS	Don't call triggers after updating. If used, the caller must later call `flatpak_installation_run_triggers()` to update the exported files. (Since: 1.0.3)

enum FlatpakInstallFlags

Flags to alter the behavior of flatpak_installation_install_full().

Members

FLATPAK_INSTALL_FLAGS_NONE	Default
FLATPAK_INSTALL_FLAGS_NO_STATIC_DELTAS	Don't use static deltas when pulling
FLATPAK_INSTALL_FLAGS_NO_DEPLOY	Don't install any new builds that might be fetched
FLATPAK_INSTALL_FLAGS_NO_PULL	Don't try to fetch new builds from the remote repo
FLATPAK_INSTALL_FLAGS_NO_TRIGGERS	Don't call triggers after installing. If used, the caller must later call `flatpak_installation_run_triggers()` to update the exported files. (Since: 1.0.3)

enum FlatpakUninstallFlags

Flags to alter the behavior of flatpak_installation_uninstall_full().

Members

FLATPAK_UNINSTALL_FLAGS_NONE	Default
FLATPAK_UNINSTALL_FLAGS_NO_PRUNE	Don't prune the local OSTree repository after uninstalling
FLATPAK_UNINSTALL_FLAGS_NO_TRIGGERS	Don't call triggers after uninstalling. If used, the caller must later call `flatpak_installation_run_triggers()` to update the exported file. (Since: 1.0.3)

Since: 0.11.8

enum FlatpakLaunchFlags

Flags to alter the behavior of flatpak_installation_launch_full().

Members

FLATPAK_LAUNCH_FLAGS_NONE	Default
FLATPAK_LAUNCH_FLAGS_DO_NOT_REAP	Do not reap the child. Use this if you want to wait for the child with `g_child_watch_add()`. (Snce: 1.1)

enum FlatpakStorageType

Flags to alter the behavior of flatpak_installation_install_full().

Members

FLATPAK_STORAGE_TYPE_DEFAULT	default
FLATPAK_STORAGE_TYPE_HARD_DISK	installation is on a hard disk
FLATPAK_STORAGE_TYPE_SDCARD	installation is on a SD card
FLATPAK_STORAGE_TYPE_MMC	installation is on an MMC
FLATPAK_STORAGE_TYPE_NETWORK	installation is on the network

Since: 0.6.15

Name

FlatpakInstalledRef — Installed application reference

Functions

const char *	flatpak_installed_ref_get_deploy_dir ()
guint64	flatpak_installed_ref_get_installed_size ()
gboolean	flatpak_installed_ref_get_is_current ()
const char *	flatpak_installed_ref_get_latest_commit ()
const char *	flatpak_installed_ref_get_origin ()
GBytes *	flatpak_installed_ref_load_metadata ()
const char * const *	flatpak_installed_ref_get_subpaths ()
const char *	flatpak_installed_ref_get_eol ()
const char *	flatpak_installed_ref_get_eol_rebase ()

Properties

gchar *	deploy-dir	Read / Write
gchar *	end-of-life	Read / Write / Construct Only
gchar *	end-of-life-rebase	Read / Write / Construct Only
guint64	installed-size	Read / Write
gboolean	is-current	Read / Write
gchar *	latest-commit	Read / Write
gchar *	origin	Read / Write
GStrv	subpaths	Read / Write

Types and Values

struct

FlatpakInstalledRef

Object Hierarchy

    GObject
    ╰── FlatpakRef
        ╰── FlatpakInstalledRef

Description

A FlatpakInstalledRef provides information about an installed application or runtime (in short: ref), such as the available builds, its size, location, etc.

Functions

flatpak_installed_ref_get_deploy_dir ()

const char *
flatpak_installed_ref_get_deploy_dir (FlatpakInstalledRef *self);

Gets the deploy dir of the ref.

Parameters

self

Returns

the deploy dir.

[transfer none]

flatpak_installed_ref_get_installed_size ()

guint64
flatpak_installed_ref_get_installed_size
                               (FlatpakInstalledRef *self);

Returns the installed size of the ref.

Parameters

self

Returns

the installed size

flatpak_installed_ref_get_is_current ()

gboolean
flatpak_installed_ref_get_is_current (FlatpakInstalledRef *self);

Returns whether the ref is current.

Parameters

self

Returns

TRUE if the ref is current

flatpak_installed_ref_get_latest_commit ()

const char *
flatpak_installed_ref_get_latest_commit
                               (FlatpakInstalledRef *self);

Gets the latest commit of the ref.

Parameters

self

Returns

the latest commit.

[transfer none][nullable]

flatpak_installed_ref_get_origin ()

const char *
flatpak_installed_ref_get_origin (FlatpakInstalledRef *self);

Gets the origin of the ref.

Parameters

self

Returns

the origin.

[transfer none]

flatpak_installed_ref_load_metadata ()

GBytes *
flatpak_installed_ref_load_metadata (FlatpakInstalledRef *self,
                                     GCancellable *cancellable,
                                     GError **error);

Loads the metadata file for this ref.

Parameters

self	a FlatpakInstalledRef
cancellable	a GCancellable.	[nullable]
error	a return location for a GError

Returns

a GBytes containing the metadata file, or NULL if an error occurred.

[transfer full]

flatpak_installed_ref_get_subpaths ()

const char * const *
flatpak_installed_ref_get_subpaths (FlatpakInstalledRef *self);

Returns the subpaths that are installed, or NULL if all files installed.

Parameters

self

Returns

A strv, or NULL.

[transfer none]

flatpak_installed_ref_get_eol ()

const char *
flatpak_installed_ref_get_eol (FlatpakInstalledRef *self);

Returns the end-of-life reason string, or NULL if the ref is not end-of-lifed.

Parameters

self

Returns

the end-of-life reason or NULL.

[transfer none]

flatpak_installed_ref_get_eol_rebase ()

const char *
flatpak_installed_ref_get_eol_rebase (FlatpakInstalledRef *self);

Returns the end-of-life rebased ref, or NULL if the ref is not end-of-lifed.

Parameters

self

Returns

the end-of-life rebased ref or NULL.

[transfer none]

Types and Values

struct FlatpakInstalledRef

struct FlatpakInstalledRef;

Property Details

The `“deploy-dir”` property

  “deploy-dir”               gchar *

Where the application is installed.

Flags: Read / Write

Default value: NULL

The `“end-of-life”` property

  “end-of-life”              gchar *

The reason for the ref to be end of life.

Flags: Read / Write / Construct Only

Default value: NULL

The `“end-of-life-rebase”` property

  “end-of-life-rebase”       gchar *

The new ref for the end-of-lifed ref.

Flags: Read / Write / Construct Only

Default value: NULL

The `“installed-size”` property

  “installed-size”           guint64

The installed size of the application.

Flags: Read / Write

Default value: 0

The `“is-current”` property

  “is-current”               gboolean

Whether the application is current.

Flags: Read / Write

Default value: FALSE

The `“latest-commit”` property

  “latest-commit”            gchar *

The latest commit.

Flags: Read / Write

Default value: NULL

The `“origin”` property

  “origin”                   gchar *

The origin.

Flags: Read / Write

Default value: NULL

The `“subpaths”` property

  “subpaths”                 GStrv

The subpaths for a partially installed ref.

Flags: Read / Write

Name

FlatpakRemoteRef — Remote application reference

Functions

const char *	flatpak_remote_ref_get_remote_name ()
guint64	flatpak_remote_ref_get_download_size ()
const char *	flatpak_remote_ref_get_eol ()
const char *	flatpak_remote_ref_get_eol_rebase ()
guint64	flatpak_remote_ref_get_installed_size ()
GBytes *	flatpak_remote_ref_get_metadata ()

Properties

guint64	download-size	Read / Write / Construct Only
gchar *	end-of-life	Read / Write / Construct Only
gchar *	end-of-life-rebase	Read / Write / Construct Only
guint64	installed-size	Read / Write / Construct Only
GBytes *	metadata	Read / Write / Construct Only
gchar *	remote-name	Read / Write / Construct Only

Types and Values

struct

FlatpakRemoteRef

Object Hierarchy

    GObject
    ╰── FlatpakRef
        ╰── FlatpakRemoteRef

Description

A FlatpakRemoteRef provides information about an application or runtime (in short: ref) that is available from a remote repository.

Functions

flatpak_remote_ref_get_remote_name ()

const char *
flatpak_remote_ref_get_remote_name (FlatpakRemoteRef *self);

Gets the remote name of the ref.

Parameters

self

Returns

the remote name.

[transfer none]

flatpak_remote_ref_get_download_size ()

guint64
flatpak_remote_ref_get_download_size (FlatpakRemoteRef *self);

Returns the download size of the ref.

Parameters

self

Returns

the download size

flatpak_remote_ref_get_eol ()

const char *
flatpak_remote_ref_get_eol (FlatpakRemoteRef *self);

Returns the end-of-life reason string, or NULL if the ref is not end-of-lifed.

Parameters

self

Returns

the end-of-life reason or NULL.

[transfer none]

flatpak_remote_ref_get_eol_rebase ()

const char *
flatpak_remote_ref_get_eol_rebase (FlatpakRemoteRef *self);

Returns the end-of-life rebased ref, or NULL if the ref is not end-of-lifed.

Parameters

self

Returns

the end-of-life rebased ref or NULL.

[transfer none]

flatpak_remote_ref_get_installed_size ()

guint64
flatpak_remote_ref_get_installed_size (FlatpakRemoteRef *self);

Returns the installed size of the ref.

Parameters

self

Returns

the installed size

flatpak_remote_ref_get_metadata ()

GBytes *
flatpak_remote_ref_get_metadata (FlatpakRemoteRef *self);

Returns the app metadata from the metadata cach of the ref.

Parameters

self

Returns

a GBytes with the metadata file contents or NULL.

[transfer none][nullable]

Types and Values

struct FlatpakRemoteRef

struct FlatpakRemoteRef;

Property Details

The `“download-size”` property

  “download-size”            guint64

The download size of the application.

Flags: Read / Write / Construct Only

Default value: 0

The `“end-of-life”` property

  “end-of-life”              gchar *

The reason for the ref to be end of life.

Flags: Read / Write / Construct Only

Default value: NULL

The `“end-of-life-rebase”` property

  “end-of-life-rebase”       gchar *

The new ref for the end of lifeed ref.

Flags: Read / Write / Construct Only

Default value: NULL

The `“installed-size”` property

  “installed-size”           guint64

The installed size of the application.

Flags: Read / Write / Construct Only

Default value: 0

The `“metadata”` property

  “metadata”                 GBytes *

The metadata info for the application.

Flags: Read / Write / Construct Only

The `“remote-name”` property

  “remote-name”              gchar *

The name of the remote.

Flags: Read / Write / Construct Only

Default value: NULL

Name

FlatpakRelatedRef — Related application reference

Functions

FlatpakRelatedRef *	flatpak_related_ref_new ()
const char * const *	flatpak_related_ref_get_subpaths ()
gboolean	flatpak_related_ref_should_download ()
gboolean	flatpak_related_ref_should_delete ()
gboolean	flatpak_related_ref_should_autoprune ()

Properties

gboolean	should-autoprune	Read / Write / Construct Only
gboolean	should-delete	Read / Write / Construct Only
gboolean	should-download	Read / Write / Construct Only
GStrv	subpaths	Read / Write / Construct Only

Types and Values

struct

FlatpakRelatedRef

Object Hierarchy

    GObject
    ╰── FlatpakRef
        ╰── FlatpakRelatedRef

Description

A FlatpakRelatedRef provides information about an ref that is related to another ref. For instance, the local extension ref of an app.

Functions

flatpak_related_ref_new ()

FlatpakRelatedRef *
flatpak_related_ref_new (const char *collection_id,
                         const char *full_ref,
                         const char *commit,
                         char **subpaths,
                         gboolean download,
                         gboolean delete);

Creates a new FlatpakRelatedRef object.

Parameters

collection_id	the collection ID.	[nullable]
full_ref	a full ref to refer to
commit	a commit ID to refer to.	[nullable]
subpaths	a nul-terminated array of subpaths.	[nullable]
download	whether to auto-download the ref with the main ref
delete	whether to auto-delete the ref with the main ref

Returns

a new ref

flatpak_related_ref_get_subpaths ()

const char * const *
flatpak_related_ref_get_subpaths (FlatpakRelatedRef *self);

Returns the subpaths that should be installed/updated for the ref. This returns NULL if all files should be installed.

Parameters

self

Returns

A strv, or NULL.

[transfer none]

Since: 0.6.7

flatpak_related_ref_should_download ()

gboolean
flatpak_related_ref_should_download (FlatpakRelatedRef *self);

Returns whether to auto-download the ref with the main ref.

Parameters

self

Returns

TRUE if the ref should be downloaded with the main ref.

Since: 0.6.7

flatpak_related_ref_should_delete ()

gboolean
flatpak_related_ref_should_delete (FlatpakRelatedRef *self);

Returns whether to auto-delete the ref with the main ref.

Parameters

self

Returns

TRUE if the ref should be deleted with the main ref.

Since: 0.6.7

flatpak_related_ref_should_autoprune ()

gboolean
flatpak_related_ref_should_autoprune (FlatpakRelatedRef *self);

Returns whether to delete when pruning unused refs.

Parameters

self

Returns

TRUE if the ref should be considered unused when pruning.

Since: 0.11.8

Types and Values

struct FlatpakRelatedRef

struct FlatpakRelatedRef;

Property Details

The `“should-autoprune”` property

  “should-autoprune”         gboolean

Whether to delete when pruning unused refs.

Flags: Read / Write / Construct Only

Default value: FALSE

The `“should-delete”` property

  “should-delete”            gboolean

Whether to auto-delete the ref with the main ref.

Flags: Read / Write / Construct Only

Default value: FALSE

The `“should-download”` property

  “should-download”          gboolean

Whether to auto-download the ref with the main ref.

Flags: Read / Write / Construct Only

Default value: FALSE

The `“subpaths”` property

  “subpaths”                 GStrv

The subpaths for a partially installed ref.

Flags: Read / Write / Construct Only

Name

FlatpakRef — Application reference

Functions

char *	flatpak_ref_format_ref ()
const char *	flatpak_ref_get_arch ()
const char *	flatpak_ref_get_branch ()
const char *	flatpak_ref_get_collection_id ()
const char *	flatpak_ref_get_commit ()
FlatpakRefKind	flatpak_ref_get_kind ()
const char *	flatpak_ref_get_name ()
FlatpakRef *	flatpak_ref_parse ()

Properties

gchar *	arch	Read / Write / Construct Only
gchar *	branch	Read / Write / Construct Only
gchar *	collection-id	Read / Write / Construct Only
gchar *	commit	Read / Write / Construct Only
FlatpakRefKind	kind	Read / Write / Construct Only
gchar *	name	Read / Write / Construct Only

Types and Values

struct	FlatpakRef
enum	FlatpakRefKind

Object Hierarchy

    GObject
    ╰── FlatpakRef
        ├── FlatpakBundleRef
        ├── FlatpakInstalledRef
        ├── FlatpakRelatedRef
        ╰── FlatpakRemoteRef

Description

Currently Flatpak manages two types of binary artifacts: applications, and runtimes. Applications contain a program that desktop users can run, while runtimes contain only libraries and data. An FlatpakRef object (or short: ref) can refer to either of these.

Both applications and runtimes are identified by a 4-tuple of strings: kind, name, arch and branch, e.g. app/org.gnome.evince/x86_64/master. The functions flatpak_ref_parse() and flatpak_ref_format_ref() can be used to convert FlatpakRef objects into this string representation and back.

FlatpakRef objects are immutable and can be passed freely between threads.

To uniquely identify a particular version of an application or runtime, you need a commit.

The subclasses FlatpakInstalledRef and FlatpakRemoteRef provide more information for artifacts that are locally installed or available from a remote repository.

Functions

flatpak_ref_format_ref ()

char *
flatpak_ref_format_ref (FlatpakRef *self);

Convert an FlatpakRef object into a string representation that can be parsed by flatpak_ref_parse().

Parameters

self

Returns

string representation.

[transfer full]

flatpak_ref_get_arch ()

const char *
flatpak_ref_get_arch (FlatpakRef *self);

Gets the arch or the ref.

Parameters

self

Returns

the arch.

[transfer none]

flatpak_ref_get_branch ()

const char *
flatpak_ref_get_branch (FlatpakRef *self);

Gets the branch of the ref.

Parameters

self

Returns

the branch.

[transfer none]

flatpak_ref_get_collection_id ()

const char *
flatpak_ref_get_collection_id (FlatpakRef *self);

Gets the collection ID of the ref.

Parameters

self

Returns

the collection ID.

[transfer none]

flatpak_ref_get_commit ()

const char *
flatpak_ref_get_commit (FlatpakRef *self);

Gets the commit of the ref.

Parameters

self

Returns

the commit.

[transfer none]

flatpak_ref_get_kind ()

FlatpakRefKind
flatpak_ref_get_kind (FlatpakRef *self);

Gets the kind of artifact that this ref refers to.

Parameters

self

Returns

the kind of artifact

flatpak_ref_get_name ()

const char *
flatpak_ref_get_name (FlatpakRef *self);

Gets the name of the ref.

Parameters

self

Returns

the name.

[transfer none]

flatpak_ref_parse ()

FlatpakRef *
flatpak_ref_parse (const char *ref,
                   GError **error);

Tries to parse a full ref name and return a FlatpakRef (without a commit set) or fail if the ref is invalid somehow.

Parameters

ref	A string ref name, such as "app/org.test.App/x86_64/master"
error	return location for a GError

Returns

an FlatpakRef, or NULL.

[transfer full]

Types and Values

struct FlatpakRef

struct FlatpakRef;

enum FlatpakRefKind

The kind of artifact that a FlatpakRef refers to.

Members

FLATPAK_REF_KIND_APP	An application
FLATPAK_REF_KIND_RUNTIME	A runtime that applications can use.

Property Details

The `“arch”` property

  “arch”                     gchar *

The architecture of the application or runtime.

Flags: Read / Write / Construct Only

Default value: NULL

The `“branch”` property

  “branch”                   gchar *

The branch of the application or runtime.

Flags: Read / Write / Construct Only

Default value: NULL

The `“collection-id”` property

  “collection-id”            gchar *

The collection ID.

Flags: Read / Write / Construct Only

Default value: NULL

The `“commit”` property

  “commit”                   gchar *

The commit.

Flags: Read / Write / Construct Only

Default value: NULL

The `“kind”` property

  “kind”                     FlatpakRefKind

The kind of artifact.

Flags: Read / Write / Construct Only

Default value: FLATPAK_REF_KIND_APP

The `“name”` property

  “name”                     gchar *

The name of the application or runtime.

Flags: Read / Write / Construct Only

Default value: NULL

Name

FlatpakRemote — Remote repository

Functions

FlatpakRemote *	flatpak_remote_new ()
const char *	flatpak_remote_get_name ()
GFile *	flatpak_remote_get_appstream_dir ()
GFile *	flatpak_remote_get_appstream_timestamp ()
char *	flatpak_remote_get_collection_id ()
void	flatpak_remote_set_collection_id ()
char *	flatpak_remote_get_default_branch ()
void	flatpak_remote_set_default_branch ()
gboolean	flatpak_remote_get_gpg_verify ()
void	flatpak_remote_set_gpg_verify ()
void	flatpak_remote_set_gpg_key ()
gboolean	flatpak_remote_get_nodeps ()
void	flatpak_remote_set_nodeps ()
gboolean	flatpak_remote_get_noenumerate ()
void	flatpak_remote_set_noenumerate ()
int	flatpak_remote_get_prio ()
void	flatpak_remote_set_prio ()
FlatpakRemoteType	flatpak_remote_get_remote_type ()
char *	flatpak_remote_get_title ()
void	flatpak_remote_set_title ()
char *	flatpak_remote_get_url ()
void	flatpak_remote_set_url ()
gboolean	flatpak_remote_get_disabled ()
void	flatpak_remote_set_disabled ()

Properties

gchar *	name	Read / Write
FlatpakRemoteType	type	Read / Write / Construct Only

Types and Values

struct	FlatpakRemote
enum	FlatpakRemoteType

Object Hierarchy

    GObject
    ╰── FlatpakRemote

Description

A FlatpakRemote object provides information about a remote repository (or short: remote) that has been configured.

At its most basic level, a remote has a name and the URL for the repository. In addition, they provide some additional information that can be useful when presenting repositories in a UI, such as a title, a priority or a "don't enumerate" flags.

To obtain FlatpakRemote objects for the configured remotes on a system, use flatpak_installation_list_remotes() or flatpak_installation_get_remote_by_name().

Functions

flatpak_remote_new ()

FlatpakRemote *
flatpak_remote_new (const char *name);

Returns a new remote object which can be used to configure a new remote.

Note: This is a local configuration object, you must commit changes using flatpak_installation_modify_remote() for the changes to take effect.

Parameters

name

a name

Returns

a new FlatpakRemote.

[transfer full]

flatpak_remote_get_name ()

const char *
flatpak_remote_get_name (FlatpakRemote *self);

Returns the name of the remote repository.

Parameters

self

Returns

the name.

[transfer none]

flatpak_remote_get_appstream_dir ()

GFile *
flatpak_remote_get_appstream_dir (FlatpakRemote *self,
                                  const char *arch);

Returns the directory where this remote will store locally cached appstream information for the specified arch .

Parameters

self	a FlatpakRemote
arch	which architecture to fetch (default: current architecture).	[nullable]

Returns

a GFile.

[transfer full]

flatpak_remote_get_appstream_timestamp ()

GFile *
flatpak_remote_get_appstream_timestamp
                               (FlatpakRemote *self,
                                const char *arch);

Returns the timestamp file that will be updated whenever the appstream information has been updated (or tried to update) for the specified arch .

Parameters

self	a FlatpakRemote
arch	which architecture to fetch (default: current architecture).	[nullable]

Returns

a GFile.

[transfer full]

flatpak_remote_get_collection_id ()

char *
flatpak_remote_get_collection_id (FlatpakRemote *self);

Returns the repository collection ID of this remote, if set.

Parameters

self

Returns

the collection ID, or NULL if unset.

[transfer full][nullable]

flatpak_remote_set_collection_id ()

void
flatpak_remote_set_collection_id (FlatpakRemote *self,
                                  const char *collection_id);

Sets the repository collection ID of this remote.

Note: This is a local modification of this object, you must commit changes using flatpak_installation_modify_remote() for the changes to take effect.

Parameters

self	a FlatpakRemote
collection_id	The new collection ID, or `NULL` to unset.	[nullable]

flatpak_remote_get_default_branch ()

char *
flatpak_remote_get_default_branch (FlatpakRemote *self);

Returns the default branch configured for the remote.

Parameters

self

Returns

the default branch, or NULL.

[transfer full]

Since: 0.6.12

flatpak_remote_set_default_branch ()

void
flatpak_remote_set_default_branch (FlatpakRemote *self,
                                   const char *default_branch);

Sets the default branch configured for this remote.

Note: This is a local modification of this object, you must commit changes using flatpak_installation_modify_remote() for the changes to take effect.

Parameters

self	a FlatpakRemote
default_branch	The new default_branch

Since: 0.6.12

flatpak_remote_get_gpg_verify ()

gboolean
flatpak_remote_get_gpg_verify (FlatpakRemote *self);

Returns whether GPG verification is enabled for the remote.

Parameters

self

Returns

whether GPG verification is enabled

flatpak_remote_set_gpg_verify ()

void
flatpak_remote_set_gpg_verify (FlatpakRemote *self,
                               gboolean gpg_verify);

Sets the gpg_verify config of this remote. See flatpak_remote_get_gpg_verify().

Note: This is a local modification of this object, you must commit changes using flatpak_installation_modify_remote() for the changes to take effect.

Parameters

self	a FlatpakRemote
gpg_verify	a bool

flatpak_remote_set_gpg_key ()

void
flatpak_remote_set_gpg_key (FlatpakRemote *self,
                            GBytes *gpg_key);

Sets the trusted gpg key for this remote.

Note: This is a local modification of this object, you must commit changes using flatpak_installation_modify_remote() for the changes to take effect.

Parameters

self	a FlatpakRemote
gpg_key	a GBytes with gpg binary key data

flatpak_remote_get_nodeps ()

gboolean
flatpak_remote_get_nodeps (FlatpakRemote *self);

Returns whether this remote should be used to find dependencies.

Parameters

self

Returns

whether the remote is marked as "don't use for dependencies"

flatpak_remote_set_nodeps ()

void
flatpak_remote_set_nodeps (FlatpakRemote *self,
                           gboolean nodeps);

Sets the nodeps config of this remote. See flatpak_remote_get_nodeps().

Note: This is a local modification of this object, you must commit changes using flatpak_installation_modify_remote() for the changes to take effect.

Parameters

self	a FlatpakRemote
nodeps	a bool

flatpak_remote_get_noenumerate ()

gboolean
flatpak_remote_get_noenumerate (FlatpakRemote *self);

Returns whether this remote should be used to list applications.

Parameters

self

Returns

whether the remote is marked as "don't enumerate"

flatpak_remote_set_noenumerate ()

void
flatpak_remote_set_noenumerate (FlatpakRemote *self,
                                gboolean noenumerate);

Sets the noenumeration config of this remote. See flatpak_remote_get_noenumerate().

Note: This is a local modification of this object, you must commit changes using flatpak_installation_modify_remote() for the changes to take effect.

Parameters

self	a FlatpakRemote
noenumerate	a bool

flatpak_remote_get_prio ()

int
flatpak_remote_get_prio (FlatpakRemote *self);

Returns the priority for the remote.

Parameters

self

Returns

the priority

flatpak_remote_set_prio ()

void
flatpak_remote_set_prio (FlatpakRemote *self,
                         int prio);

Sets the prio config of this remote. See flatpak_remote_get_prio().

Note: This is a local modification of this object, you must commit changes using flatpak_installation_modify_remote() for the changes to take effect.

Parameters

self	a FlatpakRemote
prio	a bool

flatpak_remote_get_remote_type ()

FlatpakRemoteType
flatpak_remote_get_remote_type (FlatpakRemote *self);

Get the value of “type”.

Parameters

self

Returns

the type of remote this is

Since: 0.9.8

flatpak_remote_get_title ()

char *
flatpak_remote_get_title (FlatpakRemote *self);

Returns the title of the remote.

Parameters

self

Returns

the title.

[transfer full]

flatpak_remote_set_title ()

void
flatpak_remote_set_title (FlatpakRemote *self,
                          const char *title);

Sets the repository title of this remote.

Note: This is a local modification of this object, you must commit changes using flatpak_installation_modify_remote() for the changes to take effect.

Parameters

self	a FlatpakRemote
title	The new title

flatpak_remote_get_url ()

char *
flatpak_remote_get_url (FlatpakRemote *self);

Returns the repository URL of this remote.

Parameters

self

Returns

the URL.

[transfer full]

flatpak_remote_set_url ()

void
flatpak_remote_set_url (FlatpakRemote *self,
                        const char *url);

Sets the repository URL of this remote.

Note: This is a local modification of this object, you must commit changes using flatpak_installation_modify_remote() for the changes to take effect.

Parameters

self	a FlatpakRemote
url	The new url

flatpak_remote_get_disabled ()

gboolean
flatpak_remote_get_disabled (FlatpakRemote *self);

Returns whether this remote is disabled.

Parameters

self

FlatpakTransactionProgress

Returns

whether the remote is marked as disabled

flatpak_remote_set_disabled ()

void
flatpak_remote_set_disabled (FlatpakRemote *self,
                             gboolean disabled);

Sets the disabled config of this remote. See flatpak_remote_get_disabled().

Note: This is a local modification of this object, you must commit changes using flatpak_installation_modify_remote() for the changes to take effect.

Parameters

self	a FlatpakRemote
disabled	a bool

Types and Values

struct FlatpakRemote

struct FlatpakRemote;

enum FlatpakRemoteType

Different types of FlatpakRemote .

Members

FLATPAK_REMOTE_TYPE_STATIC	Statically configured remote
FLATPAK_REMOTE_TYPE_USB	Dynamically detected local pathname remote
FLATPAK_REMOTE_TYPE_LAN	Dynamically detected network remote

Property Details

The `“name”` property

  “name”                     gchar *

Name of the remote, as used in configuration files and when interfacing with OSTree. This is typically human readable, but could be generated, and must conform to ostree_validate_remote_name(). It should typically not be presented in the UI.

Flags: Read / Write

Default value: NULL

The `“type”` property

  “type”                     FlatpakRemoteType

The type of the remote: whether it comes from static configuration files (FLATPAK_REMOTE_TYPE_STATIC ) or has been dynamically found from the local network or a mounted USB drive (FLATPAK_REMOTE_TYPE_LAN , FLATPAK_REMOTE_TYPE_USB ). Dynamic remotes may be added and removed over time.

Flags: Read / Write / Construct Only

Default value: FLATPAK_REMOTE_TYPE_STATIC

Since: 0.9.8

Name

FlatpakTransactionProgress — Progress of an operation

Functions

gboolean	flatpak_transaction_progress_get_is_estimating ()
int	flatpak_transaction_progress_get_progress ()
char *	flatpak_transaction_progress_get_status ()
void	flatpak_transaction_progress_set_update_frequency ()

Signals

void

changed

Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── FlatpakTransactionProgress

Description

FlatpakTransactionProgress is an object that represents the progress of a single operation in a transaction. You obtain a FlatpakTransactionProgress with the “new-operation” signal.

Functions

flatpak_transaction_progress_get_is_estimating ()

gboolean
flatpak_transaction_progress_get_is_estimating
                               (FlatpakTransactionProgress *self);

Gets whether the progress is currently estimating

Parameters

self

a FlatpakTransactionProgress

Returns

whether we're estimating

flatpak_transaction_progress_get_progress ()

int
flatpak_transaction_progress_get_progress
                               (FlatpakTransactionProgress *self);

Gets the current progress.

Parameters

self

a FlatpakTransactionProgress

Returns

the current progress, as an integer between 0 and 100

flatpak_transaction_progress_get_status ()

char *
flatpak_transaction_progress_get_status
                               (FlatpakTransactionProgress *self);

Gets the current status string

Parameters

self

a FlatpakTransactionProgress

Returns

the current status.

[transfer none]

flatpak_transaction_progress_set_update_frequency ()

void
flatpak_transaction_progress_set_update_frequency
                               (FlatpakTransactionProgress *self,
                                guint update_frequency);

Sets how often progress should be updated.

Parameters

self	a FlatpakTransactionProgress
update_frequency	the update frequency, in milliseconds

Types and Values

FlatpakTransactionProgress

typedef struct _FlatpakTransactionProgress FlatpakTransactionProgress;

Signal Details

The `“changed”` signal

void
user_function (FlatpakTransactionProgress *object,
               gpointer                    user_data)

Emitted when some detail of the progress object changes, you can call the various methods to get the current status.

Parameters

object	A FlatpakTransactionProgress
user_data	user data set when the signal handler was connected.

Flags: Run Last

Name

FlatpakTransactionOperation — Operation in a transaction

Functions

GFile *	flatpak_transaction_operation_get_bundle_path ()
const char *	flatpak_transaction_operation_get_commit ()
FlatpakTransactionOperationType	flatpak_transaction_operation_get_operation_type ()
const char *	flatpak_transaction_operation_get_ref ()
const char *	flatpak_transaction_operation_get_remote ()
GKeyFile *	flatpak_transaction_operation_get_metadata ()
GKeyFile *	flatpak_transaction_operation_get_old_metadata ()
const char *	flatpak_transaction_operation_type_to_string ()

Types and Values

FlatpakTransactionOperation

Object Hierarchy

    GObject
    ╰── FlatpakTransactionOperation

Description

FlatpakTransactionOperation is an object that represents a single operation in a transaction. You receive a FlatpakTransactionOperation object with the “new-operation” signal.

Functions

flatpak_transaction_operation_get_bundle_path ()

GFile *
flatpak_transaction_operation_get_bundle_path
                               (FlatpakTransactionOperation *self);

Gets the path to the bundle.

Parameters

self

Returns

the bundle GFile or NULL.

[transfer none]

flatpak_transaction_operation_get_commit ()

const char *
flatpak_transaction_operation_get_commit
                               (FlatpakTransactionOperation *self);

Gets the commit ID for the operation.

This information is available when the transaction is resolved, i.e. when “ready” is emitted.

Parameters

self

Returns

the commit ID.

[transfer none]

flatpak_transaction_operation_get_operation_type ()

FlatpakTransactionOperationType
flatpak_transaction_operation_get_operation_type
                               (FlatpakTransactionOperation *self);

Gets the type of the operation.

Parameters

self

Returns

the type of operation, as FlatpakTransactionOperationType

flatpak_transaction_operation_get_ref ()

const char *
flatpak_transaction_operation_get_ref (FlatpakTransactionOperation *self);

Gets the ref that the operation applies to.

Parameters

self

Returns

the ref.

[transfer none]

flatpak_transaction_operation_get_remote ()

const char *
flatpak_transaction_operation_get_remote
                               (FlatpakTransactionOperation *self);

Gets the remote that the operation applies to.

Parameters

self

Returns

the remote.

[transfer none]

flatpak_transaction_operation_get_metadata ()

GKeyFile *
flatpak_transaction_operation_get_metadata
                               (FlatpakTransactionOperation *self);

Gets the metadata that will be applicable when the operation is done.

This can be compared to the current metadata returned by flatpak_transaction_operation_get_old_metadata() to find new required permissions and similar changes.

This information is available when the transaction is resolved, i.e. when “ready” is emitted.

Parameters

self

Returns

the metadata GKeyFile.

[transfer none]

flatpak_transaction_operation_get_old_metadata ()

GKeyFile *
flatpak_transaction_operation_get_old_metadata
                               (FlatpakTransactionOperation *self);

Gets the metadata current metadata for the ref that self works on. Also see flatpak_transaction_operation_get_metadata().

This information is available when the transaction is resolved, i.e. when “ready” is emitted.

Parameters

self

a FlatpakTransactionOperationType

Returns

the old metadata GKeyFile.

[transfer none]

flatpak_transaction_operation_type_to_string ()

const char *
flatpak_transaction_operation_type_to_string
                               (FlatpakTransactionOperationType kind);

Converts the operation type to a string.

Parameters

kind

Returns

a string representing kind .

[transfer none]

Types and Values

FlatpakTransactionOperation

typedef struct _FlatpakTransactionOperation FlatpakTransactionOperation;

Name

FlatpakTransaction — Transaction information

Functions

FlatpakTransaction *	flatpak_transaction_new_for_installation ()
gboolean	flatpak_transaction_add_install ()
gboolean	flatpak_transaction_add_install_bundle ()
gboolean	flatpak_transaction_add_install_flatpakref ()
gboolean	flatpak_transaction_add_update ()
gboolean	flatpak_transaction_add_uninstall ()
void	flatpak_transaction_add_default_dependency_sources ()
void	flatpak_transaction_add_dependency_source ()
gboolean	flatpak_transaction_run ()
FlatpakTransactionOperation *	flatpak_transaction_get_current_operation ()
FlatpakInstallation *	flatpak_transaction_get_installation ()
GList *	flatpak_transaction_get_operations ()
gboolean	flatpak_transaction_is_empty ()
void	flatpak_transaction_set_disable_dependencies ()
void	flatpak_transaction_set_disable_prune ()
void	flatpak_transaction_set_disable_related ()
void	flatpak_transaction_set_disable_static_deltas ()
void	flatpak_transaction_set_no_deploy ()
void	flatpak_transaction_set_no_pull ()
void	flatpak_transaction_set_reinstall ()
void	flatpak_transaction_set_force_uninstall ()
void	flatpak_transaction_set_default_arch ()

Properties

FlatpakInstallation *

installation

Read / Write / Construct Only

Signals

gboolean	add-new-remote	Run Last
gint	choose-remote-for-ref	Run Last
void	end-of-lifed	Run Last
void	new-operation	Run Last
void	operation-done	Run Last
gboolean	operation-error	Run Last
gboolean	ready	Run Last

Types and Values

	FlatpakTransaction
enum	FlatpakTransactionOperationType
enum	FlatpakTransactionErrorDetails
enum	FlatpakTransactionRemoteReason
enum	FlatpakTransactionResult

Object Hierarchy

    GObject
    ╰── FlatpakTransaction

Implemented Interfaces

FlatpakTransaction implements GInitable.

Description

FlatpakTransaction is an object representing an install/update transaction. You create an object like this using flatpak_transaction_new_for_installation() and then you add all the operations (installs, updates, etc) you wish to do. Then you start the transaction with flatpak_transaction_run() which will resolve all kinds of dependencies and report progress and status while downloading and installing these.

The dependency resolution that is the first step of executing a transaction can be influenced by flatpak_transaction_set_disable_dependencies(), flatpak_transaction_set_disable_related(), flatpak_transaction_add_dependency_source() and flatpak_transaction_add_default_dependency_sources().

The underlying operations that get orchestrated by a FlatpakTransaction are: pulling new data from remote repositories, deploying newer applications or runtimes and pruning old deployments. Which of these operations are carried out can be controlled with flatpak_transaction_set_no_pull(), flatpak_transaction_set_no_deploy() and flatpak_transaction_set_disable_prune().

A transaction is a blocking operation, and all signals are emitted in the same thread. This means you should either handle the signals directly (say, by doing blocking console interaction, or by just returning without interaction), or run the operation in a separate thread and do your own forwarding to the GUI thread.

Despite the name, a FlatpakTransaction is more like a batch operation than a transaction in the database sense. Individual operations are carried out sequentially, and are atomic. They become visible to the system as they are completed. When an error occurs, already completed operations are not rolled back.

For each operation that is executed during a transaction, you first get a “new-operation” signal, followed by either a “operation-done” or “operation-error”.

The FlatpakTransaction API is threadsafe in the sense that it is safe to run two transactions at the same time, in different threads (or processes).

Functions

flatpak_transaction_new_for_installation ()

FlatpakTransaction *
flatpak_transaction_new_for_installation
                               (FlatpakInstallation *installation,
                                GCancellable *cancellable,
                                GError **error);

Creates a new FlatpakTransaction object that can be used to do installation and updates of multiple refs, as well as their dependencies, in a single operation. Set the options you want on the transaction and add the refs you want to install/update, then start the transaction with flatpak_transaction_run().

Parameters

installation	a FlatpakInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a FlatpakTransaction, or NULL on failure.

[transfer full]

flatpak_transaction_add_install ()

gboolean
flatpak_transaction_add_install (FlatpakTransaction *self,
                                 const char *remote,
                                 const char *ref,
                                 const char **subpaths,
                                 GError **error);

Adds installing the given ref to this transaction.

The remote can either be a configured remote of the installation, or a file:// uri pointing at a local repository to install from, in which case an origin remote is created.

Parameters

self	a FlatpakTransaction
remote	the name of the remote
ref	the ref
subpaths	subpaths to install, or the empty list or `NULL` to pull all subpaths.	[nullable][array zero-terminated=1]
error	return location for a GError

Returns

TRUE on success; FALSE with error set on failure.

flatpak_transaction_add_install_bundle ()

gboolean
flatpak_transaction_add_install_bundle
                               (FlatpakTransaction *self,
                                GFile *file,
                                GBytes *gpg_data,
                                GError **error);

Adds installing the given bundle to this transaction.

Parameters

self	a FlatpakTransaction
file	a GFile that is an flatpak bundle
gpg_data	GPG key with which to check bundle signatures, or `NULL` to use the key embedded in the bundle (if any).	[nullable]
error	return location for a GError

Returns

TRUE on success; FALSE with error set on failure.

flatpak_transaction_add_install_flatpakref ()

gboolean
flatpak_transaction_add_install_flatpakref
                               (FlatpakTransaction *self,
                                GBytes *flatpakref_data,
                                GError **error);

Adds installing the given flatpakref to this transaction.

Parameters

self	a FlatpakTransaction
flatpakref_data	data from a flatpakref file
error	return location for a GError

Returns

TRUE on success; FALSE with error set on failure.

flatpak_transaction_add_update ()

gboolean
flatpak_transaction_add_update (FlatpakTransaction *self,
                                const char *ref,
                                const char **subpaths,
                                const char *commit,
                                GError **error);

Adds updating the given ref to this transaction.

Parameters

self	a FlatpakTransaction
ref	the ref
subpaths	subpaths to install; `NULL` to use the current set, or `{ "", NULL }` to pull all subpaths.	[nullable][array zero-terminated=1]
commit	the commit to update to, or `NULL` to use the latest.	[nullable]
error	return location for a GError

Returns

TRUE on success; FALSE with error set on failure.

flatpak_transaction_add_uninstall ()

gboolean
flatpak_transaction_add_uninstall (FlatpakTransaction *self,
                                   const char *ref,
                                   GError **error);

Adds uninstalling the given ref to this transaction.

Parameters

self	a FlatpakTransaction
ref	the ref
error	return location for a GError

Returns

TRUE on success; FALSE with error set on failure.

flatpak_transaction_add_default_dependency_sources ()

void
flatpak_transaction_add_default_dependency_sources
                               (FlatpakTransaction *self);

Similar to flatpak_transaction_add_dependency_source(), but adds all the default installations, which means all the defined system-wide (but not per-user) installations.

Parameters

self

a FlatpakTransaction

flatpak_transaction_add_dependency_source ()

void
flatpak_transaction_add_dependency_source
                               (FlatpakTransaction *self,
                                FlatpakInstallation *installation);

Adds an extra installation as a source for application dependencies. This means that applications can be installed in this transaction relying on runtimes from this additional installation (wheres it would normally install required runtimes that are not installed in the installation the transaction works on).

Also see flatpak_transaction_add_default_dependency_sources().

Parameters

self	a FlatpakTransaction
installation	a FlatpakInstallation

flatpak_transaction_run ()

gboolean
flatpak_transaction_run (FlatpakTransaction *self,
                         GCancellable *cancellable,
                         GError **error);

Executes the transaction.

During the cause of the execution, various signal will get emitted. The FlatpakTransaction::choose-remote-for-ref and “add-new-remote” signals may get emitted while resolving operations. “ready” is emitted when the transaction has been fully resolved, and “new-operation” and “operation-done” are emitted while the operations are carried out. If an error occurs at any point during the execution, “operation-error” is emitted.

Note that this call blocks until the transaction is done.

Parameters

self	a FlatpakTransaction
cancellable	a GCancellable.	[nullable]
error	return location for an error

Returns

TRUE on success, FALSE if an error occurred

flatpak_transaction_get_current_operation ()

FlatpakTransactionOperation *
flatpak_transaction_get_current_operation
                               (FlatpakTransaction *self);

a FlatpakTransaction

Returns

TRUE if the transaction is empty

flatpak_transaction_set_disable_dependencies ()

void
flatpak_transaction_set_disable_dependencies
                               (FlatpakTransaction *self,
                                gboolean disable_dependencies);

Sets whether the transaction should ignore runtime dependencies when resolving operations for applications.

Parameters

self	a FlatpakTransaction
disable_dependencies	whether to disable runtime dependencies

flatpak_transaction_set_disable_prune ()

void
flatpak_transaction_set_disable_prune (FlatpakTransaction *self,
                                       gboolean disable_prune);

Sets whether the transaction should avoid pruning the local OSTree repository after updating.

Parameters

self	a FlatpakTransaction
disable_prune	whether to avoid pruning

flatpak_transaction_set_disable_related ()

void
flatpak_transaction_set_disable_related
                               (FlatpakTransaction *self,
                                gboolean disable_related);

Sets whether the transaction should avoid adding related refs when resolving operations. Related refs are extensions that are suggested by apps, such as locales.

Parameters

self	a FlatpakTransaction
disable_related	whether to avoid adding related refs

flatpak_transaction_set_disable_static_deltas ()

void
flatpak_transaction_set_disable_static_deltas
                               (FlatpakTransaction *self,
                                gboolean disable_static_deltas);

Sets whether the transaction should avoid using static deltas when pulling.

Parameters

self	a FlatpakTransaction
disable_static_deltas	whether to avoid static deltas

flatpak_transaction_set_no_deploy ()

void
flatpak_transaction_set_no_deploy (FlatpakTransaction *self,
                                   gboolean no_deploy);

Sets whether the transaction should download updates, but not deploy them.

Parameters

self	a FlatpakTransaction
no_deploy	whether to avoid deploying

flatpak_transaction_set_no_pull ()

void
flatpak_transaction_set_no_pull (FlatpakTransaction *self,
                                 gboolean no_pull);

Sets whether the transaction should operate only on locally available data.

Parameters

self	a FlatpakTransaction
no_pull	whether to avoid pulls

flatpak_transaction_set_reinstall ()

void
flatpak_transaction_set_reinstall (FlatpakTransaction *self,
                                   gboolean reinstall);

Sets whether the transaction should uninstall first if a ref is already installed.

Parameters

self	a FlatpakTransaction
reinstall	whether to reinstall refs

flatpak_transaction_set_force_uninstall ()

void
flatpak_transaction_set_force_uninstall
                               (FlatpakTransaction *self,
                                gboolean force_uninstall);

Sets whether the transaction should uninstall files even if they're used by a running application.

Parameters

self	a FlatpakTransaction
force_uninstall	whether to force-uninstall refs

flatpak_transaction_set_default_arch ()

void
flatpak_transaction_set_default_arch (FlatpakTransaction *self,
                                      const char *arch);

Sets the architecture to default to where it is unspecified.

Parameters

self	a FlatpakTransaction
arch	the arch to make default

Types and Values

FlatpakTransaction

typedef struct _FlatpakTransaction FlatpakTransaction;

enum FlatpakTransactionOperationType

The type of a FlatpakTransactionOperation.

Members

FLATPAK_TRANSACTION_OPERATION_INSTALL	Install a ref from a remote
FLATPAK_TRANSACTION_OPERATION_UPDATE	Update an installed ref
FLATPAK_TRANSACTION_OPERATION_INSTALL_BUNDLE	Install a bundle from a file
FLATPAK_TRANSACTION_OPERATION_UNINSTALL	Uninstall a ref
FLATPAK_TRANSACTION_OPERATION_LAST_TYPE	The (currently) last operation type

enum FlatpakTransactionErrorDetails

The details for “operation-error”.

Members

FLATPAK_TRANSACTION_ERROR_DETAILS_NON_FATAL

The operation failure was not fatal

enum FlatpakTransactionRemoteReason

The reason for “add-new-remote”.

Members

FLATPAK_TRANSACTION_REMOTE_GENERIC_REPO	The remote specified in the flatpakref has other apps too
FLATPAK_TRANSACTION_REMOTE_RUNTIME_DEPS	The remote has runtimes needed for the app

enum FlatpakTransactionResult

The details for “operation-done”.

Members

FLATPAK_TRANSACTION_RESULT_NO_CHANGE

The update caused no changes

Property Details

The `“installation”` property

  “installation”             FlatpakInstallation *

The installation that the transaction operates on.

Flags: Read / Write / Construct Only

Signal Details

The `“add-new-remote”` signal

gboolean
user_function (FlatpakTransaction *object,
               gint                reason,
               gchar              *from_id,
               gchar              *suggested_remote_name,
               gchar              *url,
               gpointer            user_data)

The ::add-new-remote signal gets emitted if, as part of the transaction, it is required or recommended that a new remote is added, for the reason described in reason .

Parameters

object	A FlatpakTransaction
reason	A FlatpakTransactionRemoteReason for this suggestion
from_id	The id of the app/runtime
suggested_remote_name	The suggested remote name
url	The repo url
user_data	user data set when the signal handler was connected.

Returns

TRUE to add the remote

Flags: Run Last

The `“choose-remote-for-ref”` signal

gint
user_function (FlatpakTransaction *object,
               gchar              *for_ref,
               gchar              *runtime_ref,
               GStrv               remotes,
               gpointer            user_data)

The ::choose-remote-for-ref signal gets emitted when a remote needs to be selected during the execution of the transaction.

Parameters

object	A FlatpakTransaction
for_ref	The ref we are installing
runtime_ref	The ref we are looking for
remotes	the remotes that has the ref, sorted in prio order
user_data	user data set when the signal handler was connected.

Returns

the index of the remote to use, or -1 to not pick one (and fail)

Flags: Run Last

The `“end-of-lifed”` signal

void
user_function (FlatpakTransaction *object,
               gchar              *ref,
               gchar              *reason,
               gchar              *rebase,
               gpointer            user_data)

The ::end-of-lifed signal gets emitted when a ref is found to be marked as end-of-life during the execution of the transaction.

Parameters

object	A FlatpakTransaction
ref	The ref we are installing
reason	The eol reason, or `NULL`
rebase	The new name, if rebased, or `NULL`
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“new-operation”` signal

void
user_function (FlatpakTransaction          *object,
               FlatpakTransactionOperation *operation,
               FlatpakTransactionProgress  *progress,
               gpointer                     user_data)

The ::new-operation signal gets emitted during the execution of the transaction when a new operation is beginning.

Parameters

object	A FlatpakTransaction
operation	The new FlatpakTransactionOperation
progress	A FlatpakTransactionProgress for `operation`
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“operation-done”` signal

void
user_function (FlatpakTransaction          *object,
               FlatpakTransactionOperation *operation,
               gchar                       *commit,
               gint                         result,
               gpointer                     user_data)

The ::operation-done signal gets emitted during the execution of the transaction when an operation is finished.

Parameters

object	A FlatpakTransaction
operation	The FlatpakTransactionOperation which finished
commit	The commit
result	A FlatpakTransactionResult giving details about the result
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“operation-error”` signal

gboolean
user_function (FlatpakTransaction          *object,
               FlatpakTransactionOperation *operation,
               GError                      *error,
               gint                         details,
               gpointer                     user_data)

The ::operation-error signal gets emitted when an error occurs during the execution of the transaction.

Parameters

object	A FlatpakTransaction
operation	The FlatpakTransactionOperation which failed
error	A GError
details	A FlatpakTransactionErrorDetails with details about the error
user_data	user data set when the signal handler was connected.

Returns

the TRUE to contine transaction, FALSE to stop

Flags: Run Last

The `“ready”` signal

gboolean
user_function (FlatpakTransaction *object,
               gpointer            user_data)

The ::ready signal is emitted when all the refs involved in the operation have been resolved to commits. At this point flatpak_transaction_get_operations() will return all the operations that will be executed as part of the transaction.

Parameters

object	A FlatpakTransaction
user_data	user data set when the signal handler was connected.

Returns

TRUE to carry on with the transaction, FALSE to abort

Flags: Run Last

Name

Version information

Functions

#define

FLATPAK_CHECK_VERSION()

Types and Values

#define	FLATPAK_MAJOR_VERSION
#define	FLATPAK_MINOR_VERSION
#define	FLATPAK_MICRO_VERSION

Description

Functions

FLATPAK_CHECK_VERSION()

#define             FLATPAK_CHECK_VERSION(major,minor,micro)

Check that the current version is at least major .minor .micro .

Parameters

major	major version to compare against
minor	minor version to compare against
micro	micro version to compare against

Types and Values

FLATPAK_MAJOR_VERSION

#define FLATPAK_MAJOR_VERSION (1)

The major version.

FLATPAK_MINOR_VERSION

#define FLATPAK_MINOR_VERSION (1)

The minor version.

FLATPAK_MICRO_VERSION

#define FLATPAK_MICRO_VERSION (2)

The micro version.

Name

Error codes

Types and Values

#define	FLATPAK_ERROR
enum	FlatpakError
#define	FLATPAK_PORTAL_ERROR
enum	FlatpakPortalError

Description

The FlatpakError and FlatpakPortalError enumerations contain error codes for some common errors.

Functions

Types and Values

FLATPAK_ERROR

#define FLATPAK_ERROR flatpak_error_quark ()

The error domain for FlatpakError errors.

enum FlatpakError

Error codes for library functions.

Members

FLATPAK_ERROR_ALREADY_INSTALLED	App/runtime is already installed
FLATPAK_ERROR_NOT_INSTALLED	App/runtime is not installed
FLATPAK_ERROR_ONLY_PULLED	App/runtime was only pulled into the local repository but not installed.
FLATPAK_ERROR_DIFFERENT_REMOTE	The App/Runtime is already installed, but from a different remote.
FLATPAK_ERROR_ABORTED	The transaction was aborted (returned TRUE in operation-error signal).
FLATPAK_ERROR_SKIPPED	The App/Runtime install was skipped due to earlier errors.
FLATPAK_ERROR_NEED_NEW_FLATPAK	The App/Runtime needs a more recent version of flatpak.
FLATPAK_ERROR_REMOTE_NOT_FOUND	The specified remote was not found.
FLATPAK_ERROR_RUNTIME_NOT_FOUND	An runtime needed for the app was not found.
FLATPAK_ERROR_DOWNGRADE	The pulled commit is a downgrade, and a downgrade wasn't specifically allowed. (Since: 1.0)
FLATPAK_ERROR_INVALID_REF	A ref could not be parsed. (Since: 1.0.3)
FLATPAK_ERROR_INVALID_DATA	Invalid data. (Since: 1.0.3)
FLATPAK_ERROR_UNTRUSTED	Missing GPG key or signature. (Since: 1.0.3)
FLATPAK_ERROR_SETUP_FAILED	Sandbox setup failed. (Since: 1.0.3)
FLATPAK_ERROR_EXPORT_FAILED	Exporting data failed. (Since: 1.0.3)
FLATPAK_ERROR_REMOTE_USED	Remote can't be uninstalled. (Since: 1.0.3)
FLATPAK_ERROR_RUNTIME_USED	Runtime can't be uninstalled. (Since: 1.0.3)
FLATPAK_ERROR_INVALID_NAME	Application, runtime or remote name is invalid. (Since: 1.0.3)

FLATPAK_PORTAL_ERROR

#define FLATPAK_PORTAL_ERROR flatpak_portal_error_quark ()

The error domain for FlatpakPortalError errors.

enum FlatpakPortalError

Members

FLATPAK_PORTAL_ERROR_FAILED	General portal failure
FLATPAK_PORTAL_ERROR_INVALID_ARGUMENT	An argument was invalid
FLATPAK_PORTAL_ERROR_NOT_FOUND	The object was not fount
FLATPAK_PORTAL_ERROR_EXISTS	The object already exists
FLATPAK_PORTAL_ERROR_NOT_ALLOWED	The call was not allowed
FLATPAK_PORTAL_ERROR_CANCELLED	The call was cancelled by the user
FLATPAK_PORTAL_ERROR_WINDOW_DESTROYED	The window was destroyed by the user

Name

FlatpakBundleRef — Application bundle reference

Functions

FlatpakBundleRef *	flatpak_bundle_ref_new ()
GFile *	flatpak_bundle_ref_get_file ()
GBytes *	flatpak_bundle_ref_get_metadata ()
GBytes *	flatpak_bundle_ref_get_appstream ()
GBytes *	flatpak_bundle_ref_get_icon ()
char *	flatpak_bundle_ref_get_origin ()
guint64	flatpak_bundle_ref_get_installed_size ()
char *	flatpak_bundle_ref_get_runtime_repo_url ()

Properties

GFile *

file

Read / Write / Construct Only

Types and Values

struct

FlatpakBundleRef

Object Hierarchy

    GObject
    ╰── FlatpakRef
        ╰── FlatpakBundleRef

Description

A FlatpakBundleRef refers to a single-file bundle containing an application or runtime.

Functions

flatpak_bundle_ref_new ()

FlatpakBundleRef *
flatpak_bundle_ref_new (GFile *file,
                        GError **error);

Creates a new bundle ref for the given file.

Parameters

file	a GFile
error	return location for an error.	[allow-none]

Returns

a new bundle ref.

flatpak_bundle_ref_get_file ()

GFile *
flatpak_bundle_ref_get_file (FlatpakBundleRef *self);

Get the file this bundle is stored in.

Parameters

self

Returns

(transfer full) : an GFile

flatpak_bundle_ref_get_metadata ()

GBytes *
flatpak_bundle_ref_get_metadata (FlatpakBundleRef *self);

Get the metadata for the app/runtime

Parameters

self

Returns

(transfer full) : an GBytes with the metadata contents, or NULL

flatpak_bundle_ref_get_appstream ()

GBytes *
flatpak_bundle_ref_get_appstream (FlatpakBundleRef *self);

Get the compressed appstream for the app/runtime

Parameters

self

Returns

(transfer full) : an GBytes with the appstream contents, or NULL

flatpak_bundle_ref_get_icon ()

GBytes *
flatpak_bundle_ref_get_icon (FlatpakBundleRef *self,
                             int size);

Get the icon png data for the app/runtime

Parameters

self	a FlatpakBundleRef
size	64 or 128

Returns

(transfer full) : an GBytes with png contents

flatpak_bundle_ref_get_origin ()

char *
flatpak_bundle_ref_get_origin (FlatpakBundleRef *self);

Get the origin url stored in the bundle

Parameters

self

Returns

(transfer full) : an url string, or NULL

flatpak_bundle_ref_get_installed_size ()

guint64
flatpak_bundle_ref_get_installed_size (FlatpakBundleRef *self);

Returns the installed size for the bundle.

Parameters

self

a FlatpakBundleRef

Returns

the installed size

flatpak_bundle_ref_get_runtime_repo_url ()

char *
flatpak_bundle_ref_get_runtime_repo_url
                               (FlatpakBundleRef *self);

Get the runtime flatpakrepo url stored in the bundle (if any)

Parameters

self

Returns

(transfer full) : an url string, or NULL

Since: 0.8.0

Types and Values

struct FlatpakBundleRef

struct FlatpakBundleRef;

Property Details

The `“file”` property

  “file”                     GFile *

The bundle file that this ref refers to.

Flags: Read / Write / Construct Only

Name

FlatpakInstance — Information about a running sandbox

Functions

GPtrArray *	flatpak_instance_get_all ()
const char *	flatpak_instance_get_id ()
const char *	flatpak_instance_get_app ()
const char *	flatpak_instance_get_arch ()
const char *	flatpak_instance_get_branch ()
const char *	flatpak_instance_get_commit ()
const char *	flatpak_instance_get_runtime ()
const char *	flatpak_instance_get_runtime_commit ()
int	flatpak_instance_get_pid ()
int	flatpak_instance_get_child_pid ()
GKeyFile *	flatpak_instance_get_info ()
gboolean	flatpak_instance_is_running ()

Types and Values

struct

FlatpakInstance

Object Hierarchy

    GObject
    ╰── FlatpakInstance

Description

A FlatpakInstance refers to a running sandbox, and contains some basic information about the sandbox setup, such as the application and runtime used inside the sandbox.

Importantly, it also gives access to the PID of the main processes in the sandbox.

One way to obtain FlatpakInstances is to use flatpak_instance_get_all(). Another way is to use flatpak_installation_launch_full().

Note that process lifecycle tracking is fundamentally racy. You have to be prepared for the sandbox and the processes represented by a FlatpakInstance to not be around anymore.

The FlatpakInstance api was added in Flatpak 1.1.

Functions

flatpak_instance_get_all ()

GPtrArray *
flatpak_instance_get_all (void);

Gets FlatpakInstance objects for all running sandboxes in the current session.

Returns

a GPtrArray of FlatpakInstance objects.

[transfer full][element-type FlatpakInstance]

Since: 1.1

flatpak_instance_get_id ()

const char *
flatpak_instance_get_id (FlatpakInstance *self);

Gets the instance ID. The ID is used by Flatpak for bookkeeping purposes and has no further relevance.

Parameters

self

Returns

the instance ID

Since: 1.1

flatpak_instance_get_app ()

const char *
flatpak_instance_get_app (FlatpakInstance *self);

Gets the application ID of the application running in the instance.

Parameters

self

Returns

the application ID

Since: 1.1

flatpak_instance_get_arch ()

const char *
flatpak_instance_get_arch (FlatpakInstance *self);

Gets the architecture of the application running in the instance.

Parameters

self

Returns

the architecture

Since: 1.1

flatpak_instance_get_branch ()

const char *
flatpak_instance_get_branch (FlatpakInstance *self);

Gets the branch of the application running in the instance.

Parameters

self

Returns

the architecture

Since: 1.1

flatpak_instance_get_commit ()

const char *
flatpak_instance_get_commit (FlatpakInstance *self);

Gets the commit of the application running in the instance.

Parameters

self

Returns

the commit

Since: 1.1

flatpak_instance_get_runtime ()

const char *
flatpak_instance_get_runtime (FlatpakInstance *self);

Gets the ref of the runtime used in the instance.

Parameters

self

Returns

the runtime ref

Since: 1.1

flatpak_instance_get_runtime_commit ()

const char *
flatpak_instance_get_runtime_commit (FlatpakInstance *self);

Gets the commit of the runtime used in the instance.

Parameters

self

Returns

the runtime commit

Since: 1.1

flatpak_instance_get_pid ()

int
flatpak_instance_get_pid (FlatpakInstance *self);

Gets the PID of the outermost process in the sandbox. This is not the application process itself, but a bubblewrap 'babysitter' process.

See flatpak_instance_get_child_pid().

Parameters

self

Returns

the outermost process PID

Since: 1.1

flatpak_instance_get_child_pid ()

int
flatpak_instance_get_child_pid (FlatpakInstance *self);

Gets the PID of the application process in the sandbox.

See flatpak_instance_get_pid().

Note that this function may return 0 immediately after launching a sandbox, for a short amount of time.

Parameters

self

Returns

the application process PID

Since: 1.1

flatpak_instance_get_info ()

GKeyFile *
flatpak_instance_get_info (FlatpakInstance *self);

Gets a keyfile that holds information about the running sandbox.

This file is available as /.flatpak-info inside the sandbox as well.

The most important data in the keyfile is available with separate getters, but there may be more information in the keyfile.

Parameters

self

Returns

the flatpak-info keyfile

Since: 1.1

flatpak_instance_is_running ()

gboolean
flatpak_instance_is_running (FlatpakInstance *self);

Finds out if the sandbox represented by self is still running.

Parameters

self