## EShellBackend

EShellBackend — dynamically loaded capabilities

## Synopsis

    #include <shell/e-shell-backend.h>

    struct              EShellBackend;
    gint                e_shell_backend_compare             (EShellBackend *shell_backend_a,
                                                             EShellBackend *shell_backend_b);
    const gchar *       e_shell_backend_get_config_dir      (EShellBackend *shell_backend);
    const gchar *       e_shell_backend_get_data_dir        (EShellBackend *shell_backend);
    struct _EShell *    e_shell_backend_get_shell           (EShellBackend *shell_backend);
    void                e_shell_backend_add_activity        (EShellBackend *shell_backend,
                                                             EActivity *activity);
    void                e_shell_backend_cancel_all          (EShellBackend *shell_backend);
    gboolean            e_shell_backend_is_busy             (EShellBackend *shell_backend);
    const gchar *       e_shell_backend_get_prefer_new_item (EShellBackend *shell_backend);
    void                e_shell_backend_set_prefer_new_item (EShellBackend *shell_backend,
                                                             const gchar *prefer_new_item);
    void                e_shell_backend_start               (EShellBackend *shell_backend);
    gboolean            e_shell_backend_is_started          (EShellBackend *shell_backend);
    gboolean            e_shell_backend_migrate             (EShellBackend *shell_backend,
                                                             gint major,
                                                             gint minor,
                                                             gint micro,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----EExtension
             +----EShellBackend

## Properties

      "busy"                     gboolean              : Read
      "prefer-new-item"          gchar*                : Read / Write

## Signals

      "activity-added"                                 : Run Last

## Description

## Details

### struct EShellBackend

    struct EShellBackend;

Contains only private data that should be read and manipulated using the functions below.

### e_shell_backend_compare ()

    gint                e_shell_backend_compare             (EShellBackend *shell_backend_a,
                                                             EShellBackend *shell_backend_b);

Using the <structfield>sort_order</structfield> field from both backends' EShellBackendClass, compares `shell_backend_a` with `shell_mobule_b` and returns -1, 0 or +1 if `shell_backend_a` is found to be less than, equal to or greater than `shell_backend_b`, respectively.

`shell_backend_a` : | an EShellBackend
`shell_backend_b` : | an EShellBackend
Returns : | -1, 0 or +1, for a less than, equal to or greater than result

### e_shell_backend_get_config_dir ()

    const gchar *       e_shell_backend_get_config_dir      (EShellBackend *shell_backend);

Returns the absolute path to the configuration directory for `shell_backend`. The string is owned by `shell_backend` and should not be modified or freed.

`shell_backend` : | an EShellBackend
Returns : | the backend's configuration directory

### e_shell_backend_get_data_dir ()

    const gchar *       e_shell_backend_get_data_dir        (EShellBackend *shell_backend);

Returns the absolute path to the data directory for `shell_backend`. The string is owned by `shell_backend` and should not be modified or freed.

`shell_backend` : | an EShellBackend
Returns : | the backend's data directory

### e_shell_backend_get_shell ()

    struct _EShell *    e_shell_backend_get_shell           (EShellBackend *shell_backend);

Returns the EShell singleton.

`shell_backend` : | an EShellBackend
Returns : | the EShell

### e_shell_backend_add_activity ()

    void                e_shell_backend_add_activity        (EShellBackend *shell_backend,
                                                             EActivity *activity);

Emits an "activity-added" signal and tracks the `activity` until it is finalized.

`shell_backend` : | an EShellBackend
`activity` : | an EActivity

### e_shell_backend_cancel_all ()

    void                e_shell_backend_cancel_all          (EShellBackend *shell_backend);

Cancels all activities passed to `e_shell_backend_add_activity()` that have not already been finalized. Note that an EActivity can only be cancelled if it was given a GCancellable object.

Also, assuming all activities are cancellable, there may still be a delay before `e_shell_backend_is_busy()` returns `FALSE`, because some activities may not be able to respond to the cancellation request immediately. Connect to the "notify::busy" signal if you need notification of `shell_backend` becoming idle.

`shell_backend` : | an EShellBackend

### e_shell_backend_is_busy ()

    gboolean            e_shell_backend_is_busy             (EShellBackend *shell_backend);

Returns `TRUE` if any activities passed to `e_shell_backend_add_activity()` are still in progress, `FALSE` if the `shell_backend` is currently idle.

`shell_backend` : | an EShellBackend
Returns : | `TRUE` if activities are still in progress

### e_shell_backend_get_prefer_new_item ()

    const gchar *       e_shell_backend_get_prefer_new_item (EShellBackend *shell_backend);

`shell_backend` : | an EShellBackend
Returns : | Name of a preferred item in New toolbar button, `NULL` or an empty string for no preference.

Since 3.4

### e_shell_backend_set_prefer_new_item ()

    void                e_shell_backend_set_prefer_new_item (EShellBackend *shell_backend,
                                                             const gchar *prefer_new_item);

Sets name of a preferred item in New toolbar button. Use `NULL` or an empty string for no preference.

`shell_backend` : | an EShellBackend
`prefer_new_item` : | name of an item

Since 3.4

### e_shell_backend_start ()

    void                e_shell_backend_start               (EShellBackend *shell_backend);

Tells the `shell_backend` to begin loading data or running background tasks which may consume significant resources. This gets called in reponse to the user switching to the corresponding EShellView for the first time. The function is idempotent for each `shell_backend`.

`shell_backend` : | an EShellBackend

### e_shell_backend_is_started ()

    gboolean            e_shell_backend_is_started          (EShellBackend *shell_backend);

Returns whether `e_shell_backend_start()` was called for `shell_backend`.

`shell_backend` : | an EShellBackend
Returns : | whether `shell_backend` is started

### e_shell_backend_migrate ()

    gboolean            e_shell_backend_migrate             (EShellBackend *shell_backend,
                                                             gint major,
                                                             gint minor,
                                                             gint micro,
                                                             GError **error);

Attempts to migrate data and settings from version `major`.`minor`.`micro`. Returns `TRUE` if the migration was successful or if no action was necessary. Returns `FALSE` and sets `error` if the migration failed.

`shell_backend` : | an EShellBackend
`major` : | major part of version to migrate from
`minor` : | minor part of version to migrate from
`micro` : | micro part of version to migrate from
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if successful, `FALSE` otherwise

## Property Details

### The `"busy"` property

      "busy"                     gboolean              : Read

Whether any activities are still in progress.

Default value: FALSE

### The `"prefer-new-item"` property

      "prefer-new-item"          gchar*                : Read / Write

Name of an item to prefer in New toolbar button; can be NULL

Default value: NULL

## Signal Details

### The `"activity-added"` signal

    void                user_function                      (EShellBackend *shell_backend,
                                                            EActivity     *activity,
                                                            gpointer       user_data)          : Run Last

Broadcasts a newly added activity.

`shell_backend` : | the EShellBackend that emitted the signal
`activity` : | an EActivity
`user_data` : | user data set when the signal handler was connected.