ZifState

ZifState — Progress reporting

Synopsis

#define             ZIF_STATE_ERROR
struct              ZifState;
enum                ZifStateAction;
struct              ZifStateClass;
enum                ZifStateError;
gboolean            (*ZifStateErrorHandlerCb)           (const GError *error,
                                                         gpointer user_data);
gboolean            (*ZifStateLockHandlerCb)            (ZifState *state,
                                                         ZifLock *lock,
                                                         ZifLockType lock_type,
                                                         GError **error,
                                                         gpointer user_data);
gboolean            zif_state_action_start              (ZifState *state,
                                                         ZifStateAction action,
                                                         const gchar *action_hint);
gboolean            zif_state_action_stop               (ZifState *state);
const gchar *       zif_state_action_to_string          (ZifStateAction action);
gboolean            zif_state_check                     (ZifState *state,
                                                         GError **error);
#define             zif_state_done                      (state,
                                                         error)
gboolean            zif_state_done_real                 (ZifState *state,
                                                         GError **error,
                                                         const gchar *strloc);
gboolean            zif_state_error_handler             (ZifState *state,
                                                         const GError *error);
GQuark              zif_state_error_quark               (void);
#define             zif_state_finished                  (state,
                                                         error)
gboolean            zif_state_finished_real             (ZifState *state,
                                                         GError **error,
                                                         const gchar *strloc);
ZifStateAction      zif_state_get_action                (ZifState *state);
const gchar *       zif_state_get_action_hint           (ZifState *state);
gboolean            zif_state_get_allow_cancel          (ZifState *state);
GCancellable *      zif_state_get_cancellable           (ZifState *state);
ZifState *          zif_state_get_child                 (ZifState *state);
guint               zif_state_get_percentage            (ZifState *state);
guint64             zif_state_get_speed                 (ZifState *state);
ZifState *          zif_state_new                       (void);
gboolean            zif_state_reset                     (ZifState *state);
void                zif_state_set_allow_cancel          (ZifState *state,
                                                         gboolean allow_cancel);
void                zif_state_set_cancellable           (ZifState *state,
                                                         GCancellable *cancellable);
void                zif_state_set_enable_profile        (ZifState *state,
                                                         gboolean enable_profile);
void                zif_state_set_error_handler         (ZifState *state,
                                                         ZifStateErrorHandlerCb error_handler_cb,
                                                         gpointer user_data);
void                zif_state_set_lock_handler          (ZifState *state,
                                                         ZifStateLockHandlerCb lock_handler_cb,
                                                         gpointer user_data);
#define             zif_state_set_number_steps          (state,
                                                         steps)
gboolean            zif_state_set_number_steps_real     (ZifState *state,
                                                         guint steps,
                                                         const gchar *strloc);
void                zif_state_set_package_progress      (ZifState *state,
                                                         const gchar *package_id,
                                                         ZifStateAction action,
                                                         guint percentage);
gboolean            zif_state_set_percentage            (ZifState *state,
                                                         guint percentage);
void                zif_state_set_report_progress       (ZifState *state,
                                                         gboolean report_progress);
void                zif_state_set_speed                 (ZifState *state,
                                                         guint64 speed);
#define             zif_state_set_steps                 (state,
                                                         error,
                                                         value,
                                                         ...)
gboolean            zif_state_set_steps_real            (ZifState *state,
                                                         GError **error,
                                                         const gchar *strloc,
                                                         gint value,
                                                         ...);
gboolean            zif_state_take_lock                 (ZifState *state,
                                                         ZifLockType lock_type,
                                                         ZifLockMode lock_mode,
                                                         GError **error);
gboolean            zif_state_valid                     (ZifState *state);

Object Hierarchy

  GObject
   +----ZifState

Properties

  "speed"                    guint64               : Read

Signals

  "action-changed"                                 : Run Last
  "allow-cancel-changed"                           : Run Last
  "package-progress-changed"                       : Run Last
  "percentage-changed"                             : Run Last
  "subpercentage-changed"                          : Run Last

Description

Objects can use zif_state_set_percentage() if the absolute percentage is known. Percentages should always go up, not down.

Modules usually set the number of steps that are expected using zif_state_set_number_steps() and then after each section is completed, the zif_state_done() function should be called. This will automatically call zif_state_set_percentage() with the correct values.

ZifState allows sub-modules to be "chained up" to the parent module so that as the sub-module progresses, so does the parent. The child can be reused for each section, and chains can be deep.

To get a child object, you should use zif_state_get_child() and then use the result in any sub-process. You should ensure that the child is not re-used without calling zif_state_done().

There are a few nice touches in this module, so that if a module only has one progress step, the child progress is used for updates.

Example 1. Using a ZifState.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28