XdgAppInstallation: xdg-app Library Reference Manual

XdgAppInstallation

XdgAppInstallation — Installation information

Functions

XdgAppInstallation *	xdg_app_installation_new_system ()
XdgAppInstallation *	xdg_app_installation_new_user ()
XdgAppInstallation *	xdg_app_installation_new_for_path ()
gboolean	xdg_app_installation_get_is_user ()
GFile *	xdg_app_installation_get_path ()
GFileMonitor *	xdg_app_installation_create_monitor ()
XdgAppInstalledRef *	xdg_app_installation_install ()
XdgAppInstalledRef *	xdg_app_installation_update ()
gboolean	xdg_app_installation_uninstall ()
gboolean	xdg_app_installation_launch ()
XdgAppInstalledRef *	xdg_app_installation_get_current_installed_app ()
XdgAppInstalledRef *	xdg_app_installation_get_installed_ref ()
GPtrArray *	xdg_app_installation_list_installed_refs ()
GPtrArray *	xdg_app_installation_list_installed_refs_by_kind ()
GPtrArray *	xdg_app_installation_list_installed_refs_for_update ()
GPtrArray *	xdg_app_installation_list_remote_refs_sync ()
GPtrArray *	xdg_app_installation_list_remotes ()
GBytes *	xdg_app_installation_fetch_remote_metadata_sync ()
XdgAppRemoteRef *	xdg_app_installation_fetch_remote_ref_sync ()
gboolean	xdg_app_installation_fetch_remote_size_sync ()
char *	xdg_app_installation_load_app_overrides ()
gboolean	xdg_app_installation_update_appstream_sync ()
XdgAppInstalledRef *	xdg_app_installation_install_bundle ()
void	(*XdgAppProgressCallback) ()

Types and Values

struct	XdgAppInstallation
enum	XdgAppUpdateFlags

Object Hierarchy

    GObject
    ╰── XdgAppInstallation

Description

XdgAppInstallation is the toplevel object that software installers should use to operate on an xdg-apps.

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

XdgAppInstallation 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

xdg_app_installation_new_system ()

XdgAppInstallation *
xdg_app_installation_new_system (GCancellable *cancellable,
                                 GError **error);

Creates a new XdgAppInstallation for the system-wide installation.

Parameters

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

Returns

a new XdgAppInstallation.

[transfer full]

xdg_app_installation_new_user ()

XdgAppInstallation *
xdg_app_installation_new_user (GCancellable *cancellable,
                               GError **error);

Creates a new XdgAppInstallation for the per-user installation.

Parameters

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

Returns

a new XdgAppInstallation.

[transfer full]

xdg_app_installation_new_for_path ()

XdgAppInstallation *
xdg_app_installation_new_for_path (GFile *path,
                                   gboolean user,
                                   GCancellable *cancellable,
                                   GError **error);

Creates a new XdgAppInstallation 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 XdgAppInstallation.

[transfer full]

xdg_app_installation_get_is_user ()

gboolean
xdg_app_installation_get_is_user (XdgAppInstallation *self);

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

Parameters

self

a XdgAppInstallation

Returns

TRUE if self is a per-user installation

xdg_app_installation_get_path ()

GFile *
xdg_app_installation_get_path (XdgAppInstallation *self);

Returns the installation location for self .

Parameters

self

a XdgAppInstallation

Returns

an GFile.

[transfer full]

xdg_app_installation_create_monitor ()

GFileMonitor *
xdg_app_installation_create_monitor (XdgAppInstallation *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 XdgAppInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

a new GFileMonitor instance, or NULL on error.

[transfer full]

xdg_app_installation_install ()

XdgAppInstalledRef *
xdg_app_installation_install (XdgAppInstallation *self,
                              const char *remote_name,
                              XdgAppRefKind kind,
                              const char *name,
                              const char *arch,
                              const char *branch,
                              XdgAppProgressCallback progress,
                              gpointer progress_data,
                              GCancellable *cancellable,
                              GError **error);

Install a new application or runtime.

Parameters

self	a XdgAppInstallation
remote_name	name of the remote to use
kind	what this ref contains (an XdgAppRefKind)
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]

xdg_app_installation_update ()

XdgAppInstalledRef *
xdg_app_installation_update (XdgAppInstallation *self,
                             XdgAppUpdateFlags flags,
                             XdgAppRefKind kind,
                             const char *name,
                             const char *arch,
                             const char *branch,
                             XdgAppProgressCallback progress,
                             gpointer progress_data,
                             GCancellable *cancellable,
                             GError **error);

Update an application or runtime.

Parameters

self	a XdgAppInstallation
flags	an XdgAppUpdateFlags variable
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]

xdg_app_installation_uninstall ()

gboolean
xdg_app_installation_uninstall (XdgAppInstallation *self,
                                XdgAppRefKind kind,
                                const char *name,
                                const char *arch,
                                const char *branch,
                                XdgAppProgressCallback progress,
                                gpointer progress_data,
                                GCancellable *cancellable,
                                GError **error);

Uninstall an application or runtime.

Parameters

self	a XdgAppInstallation
kind	what this ref contains (an XdgAppRefKind)
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

xdg_app_installation_launch ()

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

Launch an installed application.

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

Parameters

self	a XdgAppInstallation
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

xdg_app_installation_get_current_installed_app ()

XdgAppInstalledRef *
xdg_app_installation_get_current_installed_app
                               (XdgAppInstallation *self,
                                const char *name,
                                GCancellable *cancellable,
                                GError **error);

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

Parameters

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

Returns

an XdgAppInstalledRef.

[transfer full]

xdg_app_installation_get_installed_ref ()

XdgAppInstalledRef *
xdg_app_installation_get_installed_ref
                               (XdgAppInstallation *self,
                                XdgAppRefKind 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 XdgAppInstallation
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 XdgAppInstalledRef, or NULL if an error occurred.

[transfer full]

xdg_app_installation_list_installed_refs ()

GPtrArray *
xdg_app_installation_list_installed_refs
                               (XdgAppInstallation *self,
                                GCancellable *cancellable,
                                GError **error);

Lists the installed references.

Parameters

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

Returns

an GPtrArray of XdgAppInstalledRef instances.

[transfer container][element-type XdgAppInstalledRef]

xdg_app_installation_list_installed_refs_by_kind ()

GPtrArray *
xdg_app_installation_list_installed_refs_by_kind
                               (XdgAppInstallation *self,
                                XdgAppRefKind kind,
                                GCancellable *cancellable,
                                GError **error);

Lists the installed references of a specific kind.

Parameters

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

Returns

an GPtrArray of XdgAppInstalledRef instances.

[transfer container][element-type XdgAppInstalledRef]

xdg_app_installation_list_installed_refs_for_update ()

GPtrArray *
xdg_app_installation_list_installed_refs_for_update
                               (XdgAppInstallation *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 XdgAppInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

an GPtrArray of XdgAppInstalledRef instances.

[transfer container][element-type XdgAppInstalledRef]

xdg_app_installation_list_remote_refs_sync ()

GPtrArray *
xdg_app_installation_list_remote_refs_sync
                               (XdgAppInstallation *self,
                                const char *remote_name,
                                GCancellable *cancellable,
                                GError **error);

Lists all the applications and runtimes in a remote.

Parameters

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

Returns

an GPtrArray of XdgAppRemoteRef instances.

[transfer container][element-type XdgAppRemoteRef]

xdg_app_installation_list_remotes ()

GPtrArray *
xdg_app_installation_list_remotes (XdgAppInstallation *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 XdgAppInstallation
cancellable	a GCancellable.	[nullable]
error	return location for a GError

Returns

an GPtrArray of XdgAppRemote instances.

[transfer container][element-type XdgAppRemote]

xdg_app_installation_fetch_remote_metadata_sync ()

GBytes *
xdg_app_installation_fetch_remote_metadata_sync
                               (XdgAppInstallation *self,
                                const char *remote_name,
                                const char *commit,
                                GCancellable *cancellable,
                                GError **error);

Obtains the metadata file from a commit.

This is deprecated, use xdg_app_installation_fetch_remote_metadata_sync2

Parameters

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

Returns

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

[transfer full]

xdg_app_installation_fetch_remote_ref_sync ()

XdgAppRemoteRef *
xdg_app_installation_fetch_remote_ref_sync
                               (XdgAppInstallation *self,
                                const char *remote_name,
                                XdgAppRefKind 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 XdgAppInstallation
remote_name	the name of the remote
kind	what this ref contains (an XdgAppRefKind)
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 XdgAppRemoteRef instance, or NULL.

[transfer full]

xdg_app_installation_fetch_remote_size_sync ()

gboolean
xdg_app_installation_fetch_remote_size_sync
                               (XdgAppInstallation *self,
                                const char *remote_name,
                                const char *commit,
                                guint64 *download_size,
                                guint64 *installed_size,
                                GCancellable *cancellable,
                                GError **error);

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

This is deprectated, use xdg_app_installation_fetch_remote_size_sync2 instead.

Parameters

self	a XdgAppInstallation
remote_name	the name of the remote
commit	the commit
download_size	return location for the 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

xdg_app_installation_load_app_overrides ()

char *
xdg_app_installation_load_app_overrides
                               (XdgAppInstallation *self,
                                const char *app_id,
                                GCancellable *cancellable,
                                GError **error);

Loads the metadata overrides file for an application.

Parameters

self	a XdgAppInstallation
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]

xdg_app_installation_update_appstream_sync ()

gboolean
xdg_app_installation_update_appstream_sync
                               (XdgAppInstallation *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 XdgAppInstallation
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

xdg_app_installation_install_bundle ()

XdgAppInstalledRef *
xdg_app_installation_install_bundle (XdgAppInstallation *self,
                                     GFile *file,
                                     XdgAppProgressCallback progress,
                                     gpointer progress_data,
                                     GCancellable *cancellable,
                                     GError **error);

Install an application or runtime from an xdg-app bundle file. See xdg-app-build-bundle(1) for how to create brundles.

Parameters

self	a XdgAppInstallation
file	a GFile that is an xdg-app 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]

XdgAppProgressCallback ()

void
(*XdgAppProgressCallback) (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 XdgAppInstallation

struct XdgAppInstallation;

enum XdgAppUpdateFlags

Flags to alter the behavior of xdg_app_installation_update().

Members

XDG_APP_UPDATE_FLAGS_NONE	Fetch remote builds and install the latest one (default)
XDG_APP_UPDATE_FLAGS_NO_DEPLOY	Don't install any new builds that might be fetched
XDG_APP_UPDATE_FLAGS_NO_PULL	Don't try to fetch new builds from the remote repo