Top | ![]() |
![]() |
![]() |
![]() |
FlatpakTransaction is an object representing an install/update
transaction. You create an object like this using flatpak_transaction_new_for_installation()
and then you add all the operations (installs, updates, etc) you wish to do. Then
you start the transaction with flatpak_transaction_run()
which will resolve all kinds
of dependencies and report progress and status while downloading and installing these.
The dependency resolution that is the first step of executing a transaction can
be influenced by flatpak_transaction_set_disable_dependencies()
,
flatpak_transaction_set_disable_related()
, flatpak_transaction_add_dependency_source()
and flatpak_transaction_add_default_dependency_sources()
.
The underlying operations that get orchestrated by a FlatpakTransaction are: pulling
new data from remote repositories, deploying newer applications or runtimes and pruning
old deployments. Which of these operations are carried out can be controlled with
flatpak_transaction_set_no_pull()
, flatpak_transaction_set_no_deploy()
and
flatpak_transaction_set_disable_prune()
.
A transaction is a blocking operation, and all signals are emitted in the same thread. This means you should either handle the signals directly (say, by doing blocking console interaction, or by just returning without interaction), or run the operation in a separate thread and do your own forwarding to the GUI thread.
Despite the name, a FlatpakTransaction is more like a batch operation than a transaction in the database sense. Individual operations are carried out sequentially, and are atomic. They become visible to the system as they are completed. When an error occurs, already completed operations are not rolled back.
For each operation that is executed during a transaction, you first get a “new-operation” signal, followed by either a “operation-done” or “operation-error”.
The FlatpakTransaction API is threadsafe in the sense that it is safe to run two transactions at the same time, in different threads (or processes).
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()
.
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.
gboolean flatpak_transaction_add_install_bundle (FlatpakTransaction *self
,GFile *file
,GBytes *gpg_data
,GError **error
);
Adds installing the given bundle to this transaction.
gboolean flatpak_transaction_add_install_flatpakref (FlatpakTransaction *self
,GBytes *flatpakref_data
,GError **error
);
Adds installing the given flatpakref to this transaction.
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.
gboolean flatpak_transaction_add_uninstall (FlatpakTransaction *self
,const char *ref
,GError **error
);
Adds uninstalling the given ref to this transaction.
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.
void flatpak_transaction_add_dependency_source (FlatpakTransaction *self
,FlatpakInstallation *installation
);
Adds an extra installation as a source for application dependencies. This means that applications can be installed in this transaction relying on runtimes from this additional installation (wheres it would normally install required runtimes that are not installed in the installation the transaction works on).
Also see flatpak_transaction_add_default_dependency_sources()
.
gboolean flatpak_transaction_run (FlatpakTransaction *transaction
,GCancellable *cancellable
,GError **error
);
Executes the transaction.
During the cause of the execution, various signal will get emitted. The FlatpakTransaction::choose-remote-for-ref and “add-new-remote” signals may get emitted while resolving operations. “ready” is emitted when the transaction has been fully resolved, and “new-operation” and “operation-done” are emitted while the operations are carried out. If an error occurs at any point during the execution, “operation-error” is emitted.
Note that this call blocks until the transaction is done.
FlatpakTransactionOperation *
flatpak_transaction_get_current_operation
(FlatpakTransaction *self
);
Gets the current operation.
FlatpakInstallation *
flatpak_transaction_get_installation (FlatpakTransaction *self
);
Gets the installation this transaction was created for.
GList *
flatpak_transaction_get_operations (FlatpakTransaction *self
);
Gets the list of operations.
gboolean
flatpak_transaction_is_empty (FlatpakTransaction *self
);
Returns whether the transaction contains any operations.
void flatpak_transaction_set_disable_dependencies (FlatpakTransaction *self
,gboolean disable_dependencies
);
Sets whether the transaction should ignore runtime dependencies when resolving operations for applications.
void flatpak_transaction_set_disable_prune (FlatpakTransaction *self
,gboolean disable_prune
);
Sets whether the transaction should avoid pruning the local OSTree repository after updating.
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.
void flatpak_transaction_set_disable_static_deltas (FlatpakTransaction *self
,gboolean disable_static_deltas
);
Sets whether the transaction should avoid using static deltas when pulling.
void flatpak_transaction_set_no_deploy (FlatpakTransaction *self
,gboolean no_deploy
);
Sets whether the transaction should download updates, but not deploy them.
void flatpak_transaction_set_no_pull (FlatpakTransaction *self
,gboolean no_pull
);
Sets whether the transaction should operate only on locally available data.
void flatpak_transaction_set_reinstall (FlatpakTransaction *self
,gboolean reinstall
);
Sets whether the transaction should uninstall first if a ref is already installed.
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.
void flatpak_transaction_set_default_arch (FlatpakTransaction *self
,const char *arch
);
Sets the architecture to default to where it is unspecified.
The type of a FlatpakTransactionOperation.
“installation”
property“installation” FlatpakInstallation *
The installation that the transaction operates on.
Flags: Read / Write / Construct Only
“add-new-remote”
signalgboolean user_function (FlatpakTransaction *object, gint reason, gchar *from_id, gchar *suggested_remote_name, gchar *url, gpointer user_data)
The ::add-new-remote signal gets emitted if, as part of the transaction,
it is required or recommended that a new remote is added, for the reason
described in reason
.
object |
||
reason |
A FlatpakTransactionRemoteReason for this suggestion |
|
from_id |
The id of the app/runtime |
|
suggested_remote_name |
The suggested remote name |
|
url |
The repo url |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“choose-remote-for-ref”
signalgint user_function (FlatpakTransaction *object, gchar *for_ref, gchar *runtime_ref, GStrv remotes, gpointer user_data)
The ::choose-remote-for-ref signal gets emitted when a remote needs to be selected during the execution of the transaction.
object |
||
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. |
Flags: Run Last
“end-of-lifed”
signalvoid user_function (FlatpakTransaction *object, gchar *ref, gchar *reason, gchar *rebase, gpointer user_data)
The ::end-of-lifed signal gets emitted when a ref is found to be marked as end-of-life during the execution of the transaction.
Flags: Run Last
“new-operation”
signalvoid 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.
object |
||
operation |
The new FlatpakTransactionOperation |
|
progress |
A FlatpakTransactionProgress for |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“operation-done”
signalvoid user_function (FlatpakTransaction *object, FlatpakTransactionOperation *operation, gchar *commit, gint result, gpointer user_data)
The ::operation-done signal gets emitted during the execution of the transaction when an operation is finished.
object |
||
operation |
The FlatpakTransactionOperation which finished |
|
commit |
The commit |
|
result |
A FlatpakTransactionResult giving details about the result |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“operation-error”
signalgboolean user_function (FlatpakTransaction *object, FlatpakTransactionOperation *operation, GError *error, gint details, gpointer user_data)
The ::operation-error signal gets emitted when an error occurs during the execution of the transaction.
object |
||
operation |
The FlatpakTransactionOperation which failed |
|
error |
A GError |
|
details |
A FlatpakTransactionErrorDetails with details about the error |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“ready”
signalgboolean user_function (FlatpakTransaction *object, gpointer user_data)
The ::ready signal is emitted when all the refs involved in the operation
have been resolved to commits. At this point flatpak_transaction_get_operations()
will return all the operations that will be executed as part of the
transaction.
Flags: Run Last