FlatpakInstallation

FlatpakInstallation — Installation information

Functions

FlatpakInstallation * flatpak_installation_new_system ()
FlatpakInstallation * flatpak_installation_new_user ()
FlatpakInstallation * flatpak_installation_new_for_path ()
gboolean flatpak_installation_get_is_user ()
GFile * flatpak_installation_get_path ()
GFileMonitor * flatpak_installation_create_monitor ()
FlatpakInstalledRef * flatpak_installation_install ()
FlatpakInstalledRef * flatpak_installation_update ()
gboolean flatpak_installation_uninstall ()
gboolean flatpak_installation_launch ()
FlatpakInstalledRef * flatpak_installation_get_current_installed_app ()
FlatpakInstalledRef * flatpak_installation_get_installed_ref ()
GPtrArray * flatpak_installation_list_installed_refs ()
GPtrArray * flatpak_installation_list_installed_refs_by_kind ()
GPtrArray * flatpak_installation_list_installed_refs_for_update ()
GPtrArray * flatpak_installation_list_remote_refs_sync ()
GPtrArray * flatpak_installation_list_remotes ()
FlatpakRemote * flatpak_installation_get_remote_by_name ()
GBytes * flatpak_installation_fetch_remote_metadata_sync ()
FlatpakRemoteRef * flatpak_installation_fetch_remote_ref_sync ()
gboolean flatpak_installation_fetch_remote_size_sync ()
char * flatpak_installation_load_app_overrides ()
gboolean flatpak_installation_update_appstream_sync ()
FlatpakInstalledRef * flatpak_installation_install_bundle ()
gboolean flatpak_installation_drop_caches ()
gboolean flatpak_installation_modify_remote ()
gboolean flatpak_installation_remove_remote ()
gboolean flatpak_installation_update_remote_sync ()
const char * flatpak_get_default_arch ()
void (*FlatpakProgressCallback) ()

Types and Values

Object Hierarchy

    GObject
    ╰── FlatpakInstallation

Description

FlatpakInstallation is the toplevel object that software installers should use to operate on an flatpak applications.

An FlatpakInstallation object provides information about an installation location for flatpak applications. Typical installation locations are either system-wide (in $prefix/var/lib/flatpak) or per-user (in ~/.local/share/flatpak).

FlatpakInstallation can list configured remotes as well as installed application and runtime references (in short: refs). It can also run, install, update and uninstall applications and runtimes.

Functions

flatpak_installation_new_system ()

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

Creates a new FlatpakInstallation for the system-wide installation.

Parameters

cancellable

a GCancellable.

[nullable]

error

return location for a GError

 

Returns

a new FlatpakInstallation.

[transfer full]


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

a new FlatpakInstallation.

[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

a new FlatpakInstallation.

[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

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

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.

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]

progress_data

user data passed to progress

 

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.

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]

progress_data

user data passed to progress

 

cancellable

a GCancellable.

[nullable]

error

return location for a GError

 

Returns

The ref for the newly updated app (or the same if no update) 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

 

branch

name of the branch of the app or runtime to uninstall

 

progress

the callback.

[scope call]

progress_data

user data passed to progress

 

cancellable

a GCancellable.

[nullable]

error

return location for a GError

 

Returns

TRUE on success


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

an 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

an 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

an GPtrArray of FlatpakInstalledRef instances.

[transfer container][element-type FlatpakInstalledRef]


flatpak_installation_list_remote_refs_sync ()

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

Lists all the applications and runtimes in a remote.

Parameters

self

a FlatpakInstallation

 

remote_name

the name of the remote

 

cancellable

a GCancellable.

[nullable]

error

return location for a GError

 

Returns

an GPtrArray of FlatpakRemoteRef instances.

[transfer container][element-type FlatpakRemoteRef]


flatpak_installation_list_remotes ()

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

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

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.

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 .

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

Parameters

self

a FlatpakInstallation

 

file

a GFile that is an flatpak bundle

 

progress

progress callback.

[scope call]

progress_data

user data passed to progress

 

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


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