FlatpakTransaction

FlatpakTransaction — Transaction information

Functions

FlatpakTransaction * flatpak_transaction_new_for_installation ()
void flatpak_transaction_progress_set_update_frequency ()
char * flatpak_transaction_progress_get_status ()
gboolean flatpak_transaction_progress_get_is_estimating ()
int flatpak_transaction_progress_get_progress ()
guint64 flatpak_transaction_progress_get_bytes_transferred ()
guint64 flatpak_transaction_progress_get_start_time ()
FlatpakTransactionOperationType flatpak_transaction_operation_get_operation_type ()
const char * flatpak_transaction_operation_get_ref ()
GPtrArray * flatpak_transaction_operation_get_related_to_ops ()
gboolean flatpak_transaction_operation_get_is_skipped ()
const char * flatpak_transaction_operation_get_remote ()
GFile * flatpak_transaction_operation_get_bundle_path ()
const char * flatpak_transaction_operation_get_commit ()
guint64 flatpak_transaction_operation_get_download_size ()
guint64 flatpak_transaction_operation_get_installed_size ()
GKeyFile * flatpak_transaction_operation_get_metadata ()
GKeyFile * flatpak_transaction_operation_get_old_metadata ()
const char * const * flatpak_transaction_operation_get_subpaths ()
gboolean flatpak_transaction_operation_get_requires_authentication ()
const char * flatpak_transaction_operation_type_to_string ()
void flatpak_transaction_set_no_pull ()
gboolean flatpak_transaction_get_no_pull ()
void flatpak_transaction_set_no_deploy ()
gboolean flatpak_transaction_get_no_deploy ()
void flatpak_transaction_set_disable_static_deltas ()
void flatpak_transaction_set_disable_prune ()
void flatpak_transaction_set_disable_dependencies ()
void flatpak_transaction_set_disable_related ()
void flatpak_transaction_set_disable_auto_pin ()
void flatpak_transaction_set_reinstall ()
gboolean flatpak_transaction_get_no_interaction ()
void flatpak_transaction_set_no_interaction ()
void flatpak_transaction_set_force_uninstall ()
void flatpak_transaction_set_default_arch ()
void flatpak_transaction_set_parent_window ()
const char * flatpak_transaction_get_parent_window ()
void flatpak_transaction_set_include_unused_uninstall_ops ()
gboolean flatpak_transaction_get_include_unused_uninstall_ops ()
void flatpak_transaction_set_auto_install_sdk ()
gboolean flatpak_transaction_get_auto_install_sdk ()
void flatpak_transaction_set_auto_install_debug ()
gboolean flatpak_transaction_get_auto_install_debug ()
void flatpak_transaction_add_dependency_source ()
void flatpak_transaction_add_sideload_repo ()
void flatpak_transaction_add_default_dependency_sources ()
gboolean flatpak_transaction_run ()
FlatpakTransactionOperation * flatpak_transaction_get_current_operation ()
FlatpakTransactionOperation * flatpak_transaction_get_operation_for_ref ()
FlatpakInstallation * flatpak_transaction_get_installation ()
GList * flatpak_transaction_get_operations ()
void flatpak_transaction_abort_webflow ()
void flatpak_transaction_complete_basic_auth ()
gboolean flatpak_transaction_add_install ()
gboolean flatpak_transaction_add_rebase ()
gboolean flatpak_transaction_add_install_bundle ()
gboolean flatpak_transaction_add_install_flatpakref ()
gboolean flatpak_transaction_add_update ()
gboolean flatpak_transaction_add_uninstall ()
gboolean flatpak_transaction_is_empty ()

Properties

FlatpakInstallation * installation Read / Write / Construct Only
gboolean no-interaction Read / Write

Signals

Types and Values

Object Hierarchy

    GObject
    ├── FlatpakTransaction
    ├── FlatpakTransactionOperation
    ╰── FlatpakTransactionProgress

Implemented Interfaces

FlatpakTransaction implements GInitable.

Description

FlatpakTransaction is an object representing an install/update/uninstall 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).

Note: Transactions (or any other install/update operation) to a system installation rely on the ability to create files that are readable by other users. Some users set a umask that prohibits this. Unfortunately there is no good way to work around this in a threadsafe, local way, so such setups will break by default. The flatpak commandline app works around this by calling umask(022) in the early setup, and it is recommended that other apps using libflatpak do this too.

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

void
flatpak_transaction_progress_set_update_frequency
                               (FlatpakTransactionProgress *self,
                                guint update_interval);

Sets how often progress should be updated.

Parameters

self

a FlatpakTransactionProgress

 

update_interval

the update interval, in milliseconds

 

flatpak_transaction_progress_get_status ()

char *
flatpak_transaction_progress_get_status
                               (FlatpakTransactionProgress *self);

Gets the current status string

Parameters

Returns

the current status.

[transfer full]


flatpak_transaction_progress_get_is_estimating ()

gboolean
flatpak_transaction_progress_get_is_estimating
                               (FlatpakTransactionProgress *self);

Gets whether the progress is currently estimating

Parameters

Returns

whether we're estimating


flatpak_transaction_progress_get_progress ()

int
flatpak_transaction_progress_get_progress
                               (FlatpakTransactionProgress *self);

Gets the current progress.

Parameters

Returns

the current progress, as an integer between 0 and 100


flatpak_transaction_progress_get_bytes_transferred ()

guint64
flatpak_transaction_progress_get_bytes_transferred
                               (FlatpakTransactionProgress *self);

Gets the number of bytes that have been transferred.

Parameters

Returns

the number of bytes transferred

Since: 1.1.2


flatpak_transaction_progress_get_start_time ()

guint64
flatpak_transaction_progress_get_start_time
                               (FlatpakTransactionProgress *self);

Gets the time at which this operation has started, as monotonic time.

Parameters

Returns

the start time

Since: 1.1.2


flatpak_transaction_operation_get_operation_type ()

FlatpakTransactionOperationType
flatpak_transaction_operation_get_operation_type
                               (FlatpakTransactionOperation *self);

Gets the type of the operation.

Parameters

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

Returns

the ref.

[transfer none]


flatpak_transaction_operation_get_related_to_ops ()

GPtrArray *
flatpak_transaction_operation_get_related_to_ops
                               (FlatpakTransactionOperation *self);

Gets the operation(s) which caused this operation to be added to the transaction. In the case of a runtime, it's the app(s) whose runtime it is, and/or a runtime extension in the special case of an extra-data extension that doesn't define the "NoRuntime" key. In the case of a related ref such as an extension, it's the main app or runtime. In the case of a main app or something added to the transaction by e.g. flatpak_transaction_add_install() and which is not otherwise needed, NULL or an empty array will be returned.

Note that an op will be returned even if it’s marked as to be skipped when the transaction is run. Check that using flatpak_transaction_operation_get_is_skipped().

Elements in the returned array are only safe to access while the parent FlatpakTransaction is alive.

Parameters

Returns

the FlatpakTransactionOperations this one is related to (may be NULL or an empty array, which are equivalent).

[transfer none][element-type FlatpakTransactionOperation][nullable]

Since: 1.7.3


flatpak_transaction_operation_get_is_skipped ()

gboolean
flatpak_transaction_operation_get_is_skipped
                               (FlatpakTransactionOperation *self);

Gets whether this operation will be skipped when the transaction is run. Operations are skipped in some transaction situations, for example when an app has reached end of life and needs a rebase, or when it would have been updated but no update is available. By default, skipped operations are not returned by flatpak_transaction_get_operations() — but they can be accessed by traversing the operation graph using flatpak_transaction_operation_get_related_to_ops().

Parameters

Returns

TRUE if the operation has been marked as to skip, FALSE otherwise

Since: 1.7.3


flatpak_transaction_operation_get_remote ()

const char *
flatpak_transaction_operation_get_remote
                               (FlatpakTransactionOperation *self);

Gets the remote that the operation applies to.

Parameters

Returns

the remote.

[transfer none]


flatpak_transaction_operation_get_bundle_path ()

GFile *
flatpak_transaction_operation_get_bundle_path
                               (FlatpakTransactionOperation *self);

Gets the path to the bundle.

Parameters

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

Returns

the commit ID.

[transfer none]


flatpak_transaction_operation_get_download_size ()

guint64
flatpak_transaction_operation_get_download_size
                               (FlatpakTransactionOperation *self);

Gets the maximum download size for the operation.

Note that this does not include the size of dependencies, and the actual download may be smaller, if some of the data is already available locally.

For uninstall operations, this returns 0.

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

Parameters

self

a flatpakTransactionOperation

 

Returns

the download size, in bytes

Since: 1.1.2


flatpak_transaction_operation_get_installed_size ()

guint64
flatpak_transaction_operation_get_installed_size
                               (FlatpakTransactionOperation *self);

Gets the installed size for the operation.

Note that even for a new install, the extra space required on disk may be smaller than this number, if some of the data is already available locally.

For uninstall operations, this returns 0.

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

Parameters

self

a flatpakTransactionOperation

 

Returns

the installed size, in bytes

Since: 1.1.2


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

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

Returns

the old metadata GKeyFile.

[transfer none]


flatpak_transaction_operation_get_subpaths ()

const char * const *
flatpak_transaction_operation_get_subpaths
                               (FlatpakTransactionOperation *self);

Gets the set of subpaths that will be pulled from this ref.

Some refs are only partially installed, such as translations. These are subset by the toplevel directory (typically by translation name). The subset to install can be specified at install time, but is otherwise decided based on configurations and things like the current locale and how the app was previously installed.

If there is no subsetting active, this will always return NULL (even though some other APIs also take an empty string to mean no subsetting).

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

Parameters

Returns

the set of subpaths that will be pulled, or NULL if no subsetting.

[transfer none]

Since: 1.9.1


flatpak_transaction_operation_get_requires_authentication ()

gboolean
flatpak_transaction_operation_get_requires_authentication
                               (FlatpakTransactionOperation *self);

Gets whether the given operation will require authentication to acquire needed tokens. See also the documentation for “ready-pre-auth”.

Parameters

Returns

whether self requires authentication

Since: 1.9.1


flatpak_transaction_operation_type_to_string ()

const char *
flatpak_transaction_operation_type_to_string
                               (FlatpakTransactionOperationType kind);

Converts the operation type to a string.

Parameters

Returns

a string representing kind .

[transfer none]


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

gboolean
flatpak_transaction_get_no_pull (FlatpakTransaction *self);

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

Parameters

self

a FlatpakTransaction

 

Returns

TRUE if no_pull is set, FALSE otherwise

Since: 1.5.1


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

gboolean
flatpak_transaction_get_no_deploy (FlatpakTransaction *self);

Gets whether the transaction is only downloading updates, and not deploying them.

Parameters

self

a FlatpakTransaction

 

Returns

TRUE if no_deploy is set, FALSE otherwise

Since: 1.5.1


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_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_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_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_auto_pin ()

void
flatpak_transaction_set_disable_auto_pin
                               (FlatpakTransaction *self,
                                gboolean disable_pin);

Normally the transaction pins any explicit installations so they will not be automatically removed. But this can be disabled if you don't want this behaviour.

Parameters

self

a FlatpakTransaction

 

disable_pin

whether to disable auto-pinning

 

Since: 1.9.1


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

gboolean
flatpak_transaction_get_no_interaction
                               (FlatpakTransaction *self);

Gets whether the transaction is interactive. See flatpak_transaction_set_no_interaction().

Parameters

self

a FlatpakTransaction

 

Returns

TRUE if the transaction is not interactive, FALSE otherwise

Since: 1.13.0


flatpak_transaction_set_no_interaction ()

void
flatpak_transaction_set_no_interaction
                               (FlatpakTransaction *self,
                                gboolean no_interaction);

This method can be used to prevent interactive authorization dialogs to appear for operations on self . This is useful for background operations that are not directly triggered by a user action.

By default, the setting from the parent FlatpakInstallation is used.

Parameters

self

a FlatpakTransaction

 

no_interaction

Whether to disallow interactive authorization for operations

 

Since: 1.7.3


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

 

flatpak_transaction_set_parent_window ()

void
flatpak_transaction_set_parent_window (FlatpakTransaction *self,
                                       const char *parent_window);

Sets the parent window (if any) to use for any UI show by this transaction. This is used by authenticators if they need to interact with the user during authentication.

The format of this string depends on the display system in use, and is the same as used by xdg-desktop-portal.

On X11 it should be of the form x11:$xid where $xid is the hex version of the xwindows id.

On wayland is should be wayland:$handle where handle is gotten by using the export call of the xdg-foreign-unstable wayland extension.

Parameters

self

a FlatpakTransaction

 

parent_window

whether to avoid pulls

 

Since: 1.5.1


flatpak_transaction_get_parent_window ()

const char *
flatpak_transaction_get_parent_window (FlatpakTransaction *self);

Gets the parent window set for this transaction, or NULL if unset. See flatpak_transaction_get_parent_window().

Parameters

self

a FlatpakTransaction

 

Returns

a window name, or NULL.

[transfer none]

Since: 1.5.1


flatpak_transaction_set_include_unused_uninstall_ops ()

void
flatpak_transaction_set_include_unused_uninstall_ops
                               (FlatpakTransaction *self,
                                gboolean include_unused_uninstall_ops);

When this is set to TRUE, Flatpak will add uninstall operations to the transaction for each runtime it considers unused. This is used by the "update" CLI command to garbage collect runtimes and free disk space.

No guarantees are made about the exact hueristic used; e.g. only end-of-life unused runtimes may be uninstalled with this set. To see the full list of unused runtimes in an installation, use flatpak_installation_list_unused_refs().

Parameters

self

a FlatpakTransaction

 

include_unused_uninstall_ops

whether to include unused uninstall ops

 

Since: 1.9.1


flatpak_transaction_get_include_unused_uninstall_ops ()

gboolean
flatpak_transaction_get_include_unused_uninstall_ops
                               (FlatpakTransaction *self);

Gets the value set by flatpak_transaction_set_include_unused_uninstall_ops().

Parameters

self

a FlatpakTransaction

 

Returns

TRUE if include_unused_uninstall_ops is set, FALSE otherwise

Since: 1.9.1


flatpak_transaction_set_auto_install_sdk ()

void
flatpak_transaction_set_auto_install_sdk
                               (FlatpakTransaction *self,
                                gboolean auto_install_sdk);

When this is set to TRUE, Flatpak will automatically install the SDK for each app currently being installed or updated. Does nothing if an uninstall is taking place.

Parameters

self

a FlatpakTransaction

 

auto_install_sdk

whether to auto install SDKs for apps

 

Since: 1.13.3


flatpak_transaction_get_auto_install_sdk ()

gboolean
flatpak_transaction_get_auto_install_sdk
                               (FlatpakTransaction *self);

Gets the value set by flatpak_transaction_set_auto_install_sdk().

Parameters

self

a FlatpakTransaction

 

Returns

TRUE if auto_install_sdk is set, FALSE otherwise

Since: 1.13.3


flatpak_transaction_set_auto_install_debug ()

void
flatpak_transaction_set_auto_install_debug
                               (FlatpakTransaction *self,
                                gboolean auto_install_debug);

When this is set to TRUE, Flatpak will automatically install the debug info for each app currently being installed or updated, as well as its dependencies. Does nothing if an uninstall is taking place.

Parameters

self

a FlatpakTransaction

 

auto_install_debug

whether to auto install debug info for apps

 

Since: 1.13.3


flatpak_transaction_get_auto_install_debug ()

gboolean
flatpak_transaction_get_auto_install_debug
                               (FlatpakTransaction *self);

Gets the value set by flatpak_transaction_set_auto_install_debug().

Parameters

self

a FlatpakTransaction

 

Returns

TRUE if auto_install_debug is set, FALSE otherwise

Since: 1.13.3


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 (whereas 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_add_sideload_repo ()

void
flatpak_transaction_add_sideload_repo (FlatpakTransaction *self,
                                       const char *path);

Adds an extra local ostree repo as source for installation. This is equivalent to using the sideload-repos directories (see flatpak(1)), but can be done dynamically. Any path added here is used in addition to ones in those directories.

Parameters

self

a FlatpakTransaction

 

path

a path to a local flatpak repository

 

Since: 1.7.1


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

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

Executes the transaction.

During the course of the execution, various signals 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

transaction

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

Gets the current operation.

Parameters

self

a FlatpakTransaction

 

Returns

the current FlatpakTransactionOperation.

[transfer full]


flatpak_transaction_get_operation_for_ref ()

FlatpakTransactionOperation *
flatpak_transaction_get_operation_for_ref
                               (FlatpakTransaction *self,
                                const char *remote,
                                const char *ref,
                                GError **error);

Gets the operation for ref , if any match. If remote is non-NULL, only an operation for that remote will be returned. If remote is NULL and the transaction has more than one operation for ref from different remotes, an error will be returned.

Parameters

self

a FlatpakTransaction

 

remote

a remote name.

[nullable]

ref

a ref

 

error

return location for an error

 

Returns

the FlatpakTransactionOperation for ref , or NULL with error set.

[transfer full]

Since: 1.13.3


flatpak_transaction_get_installation ()

FlatpakInstallation *
flatpak_transaction_get_installation (FlatpakTransaction *self);

Gets the installation this transaction was created for.

Parameters

Returns

a FlatpakInstallation.

[transfer full]


flatpak_transaction_get_operations ()

GList *
flatpak_transaction_get_operations (FlatpakTransaction *self);

Gets the list of operations. Skipped operations are not included. The order of the list is the order in which the operations are executed.

Parameters

self

a FlatpakTransaction

 

Returns

a GList of operations.

[transfer full][element-type FlatpakTransactionOperation]


flatpak_transaction_abort_webflow ()

void
flatpak_transaction_abort_webflow (FlatpakTransaction *self,
                                   guint id);

Cancel an ongoing webflow authentication request. This can be call in the time between “webflow-start” returned TRUE, and “webflow-done” is emitted. It will cancel the ongoing authentication operation.

This is useful for example if you're showing an authenticaion window with a browser, but the user closed it before it was finished.

Parameters

self

a FlatpakTransaction

 

id

The webflow id, as passed into the webflow-start signal

 

Since: 1.5.1


flatpak_transaction_complete_basic_auth ()

void
flatpak_transaction_complete_basic_auth
                               (FlatpakTransaction *self,
                                guint id,
                                const char *user,
                                const char *password,
                                GVariant *options);

Finishes (or aborts) an ongoing basic auth request.

Parameters

self

a FlatpakTransaction

 

id

The webflow id, as passed into the webflow-start signal

 

user

The user name, or NULL if aborting request

 

password

The password

 

options

Extra a{sv] variant with options (or NULL), currently unused.

 

Since: 1.5.2


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

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

Adds updating the previous_ids of the given ref to this transaction, via either installing the ref if it was not already present or updating it. This will treat ref as the result of following an eol-rebase, and data migration from the refs in previous_ids will be set up.

See flatpak_transaction_add_install() for a description of remote .

Parameters

self

a FlatpakTransaction

 

remote

the name of the remote

 

ref

the ref

 

subpaths

the subpaths to include, or NULL to install the complete ref.

[nullable]

previous_ids

Previous ids to add to the given ref. These should simply be the ids, not the full ref names (e.g. org.foo.Bar, not org.foo.Bar/x86_64/master).

[nullable][array zero-terminated=1]

error

return location for a GError

 

Returns

TRUE on success; FALSE with error set on failure.

Since: 1.3.3.


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 plus the set of configured languages, or { NULL } 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_is_empty ()

gboolean
flatpak_transaction_is_empty (FlatpakTransaction *self);

Returns whether the transaction contains any non-skipped operations.

Parameters

self

a FlatpakTransaction

 

Returns

TRUE if the transaction is empty

Types and Values

FLATPAK_TYPE_TRANSACTION

#define FLATPAK_TYPE_TRANSACTION flatpak_transaction_get_type ()

FLATPAK_TYPE_TRANSACTION_PROGRESS

#define FLATPAK_TYPE_TRANSACTION_PROGRESS flatpak_transaction_progress_get_type ()

FLATPAK_TYPE_TRANSACTION_OPERATION

#define FLATPAK_TYPE_TRANSACTION_OPERATION flatpak_transaction_operation_get_type ()

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 FlatpakTransactionResult

The details for “operation-done”.

Members

FLATPAK_TRANSACTION_RESULT_NO_CHANGE

The update caused no changes

 

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

 

struct FlatpakTransactionClass

struct FlatpakTransactionClass {
  GObjectClass parent_class;

  void (*new_operation)        (FlatpakTransaction          *transaction,
                                FlatpakTransactionOperation *operation,
                                FlatpakTransactionProgress  *progress);
  void (*operation_done)       (FlatpakTransaction          *transaction,
                                FlatpakTransactionOperation *operation,
                                const char                  *commit,
                                FlatpakTransactionResult     details);
  gboolean (*operation_error)  (FlatpakTransaction            *transaction,
                                FlatpakTransactionOperation   *operation,
                                const GError                  *error,
                                FlatpakTransactionErrorDetails detail);
  int (*choose_remote_for_ref) (FlatpakTransaction *transaction,
                                const char         *for_ref,
                                const char         *runtime_ref,
                                const char * const *remotes);
  void (*end_of_lifed)         (FlatpakTransaction *transaction,
                                const char         *ref,
                                const char         *reason,
                                const char         *rebase);
  gboolean (*ready)            (FlatpakTransaction *transaction);

  gboolean (*add_new_remote) (FlatpakTransaction            *transaction,
                              FlatpakTransactionRemoteReason reason,
                              const char                    *from_id,
                              const char                    *remote_name,
                              const char                    *url);

  gboolean (*run)            (FlatpakTransaction *transaction,
                              GCancellable       *cancellable,
                              GError            **error);
  gboolean (*end_of_lifed_with_rebase) (FlatpakTransaction *transaction,
                                        const char         *remote,
                                        const char         *ref,
                                        const char         *reason,
                                        const char         *rebased_to_ref,
                                        const char        **previous_ids);

  gboolean (*webflow_start) (FlatpakTransaction *transaction,
                             const char         *remote,
                             const char         *url,
                             GVariant           *options,
                             guint               id);
  void (*webflow_done) (FlatpakTransaction *transaction,
                        GVariant           *options,
                        guint               id);

  gboolean (*basic_auth_start) (FlatpakTransaction *transaction,
                                const char         *remote,
                                const char         *realm,
                                GVariant           *options,
                                guint               id);
  void (*install_authenticator)   (FlatpakTransaction *transaction,
                                   const char         *remote,
                                   const char         *authenticator_ref);

  gboolean (*ready_pre_auth) (FlatpakTransaction *transaction);

  gpointer padding[3];
};

FlatpakTransaction

typedef struct _FlatpakTransaction FlatpakTransaction;

FlatpakTransactionOperation

typedef struct _FlatpakTransactionOperation FlatpakTransactionOperation;

FlatpakTransactionProgress

typedef struct _FlatpakTransactionProgress FlatpakTransactionProgress;

Property Details

The “installation” property

  “installation”             FlatpakInstallation *

The installation that the transaction operates on.

Owner: FlatpakTransaction

Flags: Read / Write / Construct Only


The “no-interaction” property

  “no-interaction”           gboolean

TRUE if the transaction is not interactive, FALSE otherwise.

See flatpak_transaction_set_no_interaction().

Owner: FlatpakTransaction

Flags: Read / Write

Default value: FALSE

Since: 1.13.0

Signal Details

The “add-new-remote” signal

gboolean
user_function (FlatpakTransaction *object,
               int                 reason,
               char               *from_id,
               char               *suggested_remote_name,
               char               *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.

[type FlatpakTransactionRemoteReason]

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 “basic-auth-start” signal

gboolean
user_function (FlatpakTransaction *object,
               char               *remote,
               char               *realm,
               GVariant           *options,
               int                 id,
               gpointer            user_data)

The ::basic-auth-start signal gets emitted when a basic user/password authentication is needed during the operation. If the caller handles this it should ask the user for the user and password and return TRUE. Once the information is gathered call flatpak_transaction_complete_basic_auth() with it.

If the client does not support basic auth then return FALSE from this signal (or don't implement it). This will abort the authentication and likely result in the transaction failing (unless the authentication was somehow optional).

Parameters

object

A FlatpakTransaction

 

remote

The remote we're authenticating with

 

realm

The url to show

 

options

Extra options, currently unused

 

id

The id of the operation, can be used to finish it

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.5.2


The “choose-remote-for-ref” signal

int
user_function (FlatpakTransaction *object,
               char               *for_ref,
               char               *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,
               char               *ref,
               char               *reason,
               char               *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 “end-of-lifed-with-rebase” signal

gboolean
user_function (FlatpakTransaction *object,
               char               *remote,
               char               *ref,
               char               *reason,
               char               *rebased_to_ref,
               GStrv               previous_ids,
               gpointer            user_data)

The ::end-of-lifed-with-rebase signal gets emitted when a ref is found to be marked as end-of-life before the transaction begins. Unlike “end-of-lifed”, this signal allows for the transaction to be modified in order to e.g. install the rebased ref.

If the caller wants to install the rebased ref, they should call flatpak_transaction_add_uninstall() on ref , flatpak_transaction_add_rebase() on rebased_to_ref , and return TRUE. Otherwise FALSE may be returned.

Parameters

object

A FlatpakTransaction

 

remote

The remote for the ref we are processing

 

ref

The ref we are processing

 

reason

The eol reason, or NULL

 

rebased_to_ref

The new name, if rebased, or NULL

 

previous_ids

The previous names for the rebased ref (if any), including the one from ref

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the operation on this end-of-lifed ref should be skipped (e.g. because the rebased ref has been added to the transaction), FALSE if it should remain.

Flags: Run Last

Since: 1.3.2


The “install-authenticator” signal

void
user_function (FlatpakTransaction *object,
               char               *remote,
               char               *authenticator_ref,
               gpointer            user_data)

The ::install-authenticator signal gets emitted if, as part of resolving the transaction, we need to use an authenticator, but the authentication is not installed, but is available to be installed from the ref.

The application can handle this signal, and if so create another transaction to install the authenticator.

The default handler does nothing, and if the authenticator is not installed when the signal handler fails the transaction will error out.

Parameters

object

A FlatpakTransaction

 

remote

The remote name

 

authenticator_ref

The ref for the authenticator

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.8.0


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,
               char                        *commit,
               int                          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.

[nullable]

result

A FlatpakTransactionResult giving details about the result.

[type FlatpakTransactionResult]

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,
               int                          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.

[type FlatpakTransactionErrorDetails]

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, and the required authentication for all ops is gotten. 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


The “ready-pre-auth” signal

gboolean
user_function (FlatpakTransaction *object,
               gpointer            user_data)

The ::ready-pre-auth signal is emitted when all the refs involved in the transaction have been resolved to commits, but we might not necessarily have asked for authentication for all their required operations. This is very similar to the ::ready signal, and you can choose which one (or both) to use depending on how you want to handle authentication in your user interface.

At this point flatpak_transaction_get_operations() will return all the operations that will be executed as part of the transaction. You can call flatpak_transaction_operation_get_requires_authentication() to see which will require authentication.

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

Since: 1.9.1


The “webflow-done” signal

void
user_function (FlatpakTransaction *object,
               GVariant           *options,
               int                 id,
               gpointer            user_data)

The ::webflow-done signal gets emitted when the authentication finished the webflow, independent of the reason and results. If you for were showing a web-browser window it can now be closed.

Parameters

object

A FlatpakTransaction

 

options

Extra options, currently unused

 

id

The id of the operation

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.5.1


The “webflow-start” signal

gboolean
user_function (FlatpakTransaction *object,
               char               *remote,
               char               *url,
               GVariant           *options,
               int                 id,
               gpointer            user_data)

The ::webflow-start signal gets emitted when some kind of user authentication is needed during the operation. If the caller handles this it should show the url in a webbrowser and return TRUE. This will eventually cause the webbrowser to finish the authentication operation and operation will continue, as signaled by the webflow-done being emitted.

If the client does not support webflow then return FALSE from this signal (or don't implement it). This will abort the authentication and likely result in the transaction failing (unless the authentication was somehow optional).

During the time between webflow-start and webflow-done the client can call flatpak_transaction_abort_webflow() to manually abort the authentication. This is useful if the user aborted the authentication operation some way, like e.g. closing the browser window.

Parameters

object

A FlatpakTransaction

 

remote

The remote we're authenticating with

 

url

The url to show

 

options

Extra options, currently unused

 

id

The id of the operation, can be used to cancel it

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.5.1


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