FlatpakTransaction: Flatpak Library Reference Manual

## FlatpakTransaction FlatpakTransaction — Transaction information |

## Functions

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

## Properties

FlatpakInstallation * | installation | Read / Write / Construct Only

## Signals

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

## Types and Values

| FlatpakTransaction
enum | FlatpakTransactionOperationType
enum | FlatpakTransactionErrorDetails
enum | FlatpakTransactionRemoteReason
enum | FlatpakTransactionResult

## Object Hierarchy

        GObject
        ╰── FlatpakTransaction

## Implemented Interfaces

FlatpakTransaction implements GInitable.

## Description

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

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.

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

## Functions

### flatpak_transaction_new_for_installation ()

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

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

#### Parameters

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

#### Returns

a FlatpakTransaction, or `NULL` on failure.

[transfer full]

### flatpak_transaction_add_install ()

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

Adds installing the given ref to this transaction.

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

#### Parameters

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

#### Returns

`TRUE` on success; `FALSE` with `error` set on failure.

### flatpak_transaction_add_install_bundle ()

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

Adds installing the given bundle to this transaction.

#### Parameters

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

#### Returns

`TRUE` on success; `FALSE` with `error` set on failure.

### flatpak_transaction_add_install_flatpakref ()

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

Adds installing the given flatpakref to this transaction.

#### Parameters

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

#### Returns

`TRUE` on success; `FALSE` with `error` set on failure.

### flatpak_transaction_add_update ()

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

Adds updating the given ref to this transaction.

#### Parameters

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

#### Returns

`TRUE` on success; `FALSE` with `error` set on failure.

### flatpak_transaction_add_uninstall ()

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

Adds uninstalling the given ref to this transaction.

#### Parameters

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

#### Returns

`TRUE` on success; `FALSE` with `error` set on failure.

### flatpak_transaction_add_default_dependency_sources ()

    void
    flatpak_transaction_add_default_dependency_sources
                                   (FlatpakTransaction *self);

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

#### Parameters

self | a FlatpakTransaction |

### flatpak_transaction_add_dependency_source ()

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

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

#### Parameters

self | a FlatpakTransaction |
installation | a FlatpakInstallation |

### flatpak_transaction_run ()

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

Executes the transaction.

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

Note that this call blocks until the transaction is done.

#### Parameters

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

#### Returns

`TRUE` on success, `FALSE` if an error occurred

### flatpak_transaction_get_current_operation ()

    FlatpakTransactionOperation *
    flatpak_transaction_get_current_operation
                                   (FlatpakTransaction *self);

Gets the current operation.

#### Parameters

self | a FlatpakTransaction |

#### Returns

the current FlatpakTransactionOperation.

[transfer full]

### flatpak_transaction_get_installation ()

    FlatpakInstallation *
    flatpak_transaction_get_installation (FlatpakTransaction *self);

Gets the installation this transaction was created for.

#### Parameters

self | a FlatpakTransactionOperation |

#### Returns

a FlatpakInstallation.

[transfer full]

### flatpak_transaction_get_operations ()

    GList *
    flatpak_transaction_get_operations (FlatpakTransaction *self);

Gets the list of operations.

#### Parameters

self | a FlatpakTransaction |

#### Returns

a GList of operations.

[transfer full][element-type FlatpakTransactionOperation]

### flatpak_transaction_is_empty ()

    gboolean
    flatpak_transaction_is_empty (FlatpakTransaction *self);

Returns whether the transaction contains any operations.

#### Parameters

self | a FlatpakTransaction |

#### Returns

`TRUE` if the transaction is empty

### flatpak_transaction_set_disable_dependencies ()

    void
    flatpak_transaction_set_disable_dependencies
                                   (FlatpakTransaction *self,
                                    gboolean disable_dependencies);

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

#### Parameters

self | a FlatpakTransaction |
disable_dependencies | whether to disable runtime dependencies |

### flatpak_transaction_set_disable_prune ()

    void
    flatpak_transaction_set_disable_prune (FlatpakTransaction *self,
                                           gboolean disable_prune);

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

#### Parameters

self | a FlatpakTransaction |
disable_prune | whether to avoid pruning |

### flatpak_transaction_set_disable_related ()

    void
    flatpak_transaction_set_disable_related
                                   (FlatpakTransaction *self,
                                    gboolean disable_related);

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

#### Parameters

self | a FlatpakTransaction |
disable_related | whether to avoid adding related refs |

### flatpak_transaction_set_disable_static_deltas ()

    void
    flatpak_transaction_set_disable_static_deltas
                                   (FlatpakTransaction *self,
                                    gboolean disable_static_deltas);

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

#### Parameters

self | a FlatpakTransaction |
disable_static_deltas | whether to avoid static deltas |

### flatpak_transaction_set_no_deploy ()

    void
    flatpak_transaction_set_no_deploy (FlatpakTransaction *self,
                                       gboolean no_deploy);

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

#### Parameters

self | a FlatpakTransaction |
no_deploy | whether to avoid deploying |

### flatpak_transaction_set_no_pull ()

    void
    flatpak_transaction_set_no_pull (FlatpakTransaction *self,
                                     gboolean no_pull);

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

#### Parameters

self | a FlatpakTransaction |
no_pull | whether to avoid pulls |

### flatpak_transaction_set_reinstall ()

    void
    flatpak_transaction_set_reinstall (FlatpakTransaction *self,
                                       gboolean reinstall);

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

#### Parameters

self | a FlatpakTransaction |
reinstall | whether to reinstall refs |

### flatpak_transaction_set_force_uninstall ()

    void
    flatpak_transaction_set_force_uninstall
                                   (FlatpakTransaction *self,
                                    gboolean force_uninstall);

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

#### Parameters

self | a FlatpakTransaction |
force_uninstall | whether to force-uninstall refs |

### flatpak_transaction_set_default_arch ()

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

Sets the architecture to default to where it is unspecified.

#### Parameters

self | a FlatpakTransaction |
arch | the arch to make default |

## Types and Values

### FlatpakTransaction

    typedef struct _FlatpakTransaction FlatpakTransaction;

### enum FlatpakTransactionOperationType

The type of a FlatpakTransactionOperation.

#### Members

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

### enum FlatpakTransactionErrorDetails

The details for “operation-error”.

#### Members

FLATPAK_TRANSACTION_ERROR_DETAILS_NON_FATAL | The operation failure was not fatal |

### enum FlatpakTransactionRemoteReason

The reason for “add-new-remote”.

#### Members

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

### enum FlatpakTransactionResult

The details for “operation-done”.

#### Members

FLATPAK_TRANSACTION_RESULT_NO_CHANGE | The update caused no changes |

## Property Details

### The `“installation”` property

      “installation”             FlatpakInstallation *

The installation that the transaction operates on.

Owner: FlatpakTransaction

Flags: Read / Write / Construct Only

## Signal Details

### The `“add-new-remote”` signal

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

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

#### Parameters

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

#### Returns

`TRUE` to add the remote

Flags: Run Last

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

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

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

#### Parameters

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

#### Returns

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

Flags: Run Last

### The `“end-of-lifed”` signal

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

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

#### Parameters

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

Flags: Run Last

### The `“end-of-lifed-with-rebase”` signal

    gboolean
    user_function (FlatpakTransaction *flatpaktransaction,
                   gchar              *arg1,
                   gchar              *arg2,
                   gchar              *arg3,
                   gchar              *arg4,
                   GStrv               arg5,
                   gpointer            user_data)

Flags: Run Last

### The `“new-operation”` signal

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

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

#### Parameters

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

Flags: Run Last

### The `“operation-done”` signal

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

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

#### Parameters

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

Flags: Run Last

### The `“operation-error”` signal

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

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

#### Parameters

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

#### Returns

the `TRUE` to contine transaction, `FALSE` to stop

Flags: Run Last

### The `“ready”` signal

    gboolean
    user_function (FlatpakTransaction *object,
                   gpointer            user_data)

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

#### Parameters

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

#### Returns

`TRUE` to carry on with the transaction, `FALSE` to abort

Flags: Run Last