FuProgress: fwupd Reference Manual

## FuProgress FuProgress |

## Functions

FuProgress * | fu_progress_new ()
const gchar * | fu_progress_get_id ()
void | fu_progress_set_id ()
const gchar * | fu_progress_flag_to_string ()
FuProgressFlags | fu_progress_flag_from_string ()
void | fu_progress_add_flag ()
void | fu_progress_remove_flag ()
gboolean | fu_progress_has_flag ()
FwupdStatus | fu_progress_get_status ()
void | fu_progress_set_status ()
void | fu_progress_set_percentage ()
void | fu_progress_set_percentage_full ()
guint | fu_progress_get_percentage ()
void | fu_progress_set_profile ()
void | fu_progress_reset ()
void | fu_progress_set_steps ()
guint | fu_progress_get_steps ()
void | fu_progress_add_step ()
void | fu_progress_finished ()
void | fu_progress_step_done ()
FuProgress * | fu_progress_get_child ()
void | fu_progress_sleep ()

## Types and Values

#define | FU_TYPE_PROGRESS
struct | FuProgressClass
typedef | FuProgressFlags
#define | FU_PROGRESS_FLAG_NONE
#define | FU_PROGRESS_FLAG_UNKNOWN
#define | FU_PROGRESS_FLAG_GUESSED
#define | FU_PROGRESS_FLAG_NO_PROFILE
| FuProgress

## Description

## Functions

### fu_progress_new ()

    FuProgress *
    fu_progress_new (const gchar *id);

#### Parameters

id | progress ID, normally `G_STRLOC`. | [nullable]

#### Returns

A new FuProgress instance.

Since: 1.7.0

### fu_progress_get_id ()

    const gchar *
    fu_progress_get_id (FuProgress *self);

Return the id of the progress, which is normally set by the caller.

#### Parameters

self | a FuProgress |

#### Returns

progress ID

Since: 1.7.0

### fu_progress_set_id ()

    void
    fu_progress_set_id (FuProgress *self,
                        const gchar *id);

Sets the id of the progress.

#### Parameters

self | a FuProgress |
id | progress ID, normally `G_STRLOC` |

Since: 1.7.0

### fu_progress_flag_to_string ()

    const gchar *
    fu_progress_flag_to_string (FuProgressFlags flag);

Converts an progress flag to a string.

#### Parameters

flag | an internal progress flag, e.g. `FU_PROGRESS_FLAG_GUESSED` |

#### Returns

identifier string

Since: 1.7.0

### fu_progress_flag_from_string ()

    FuProgressFlags
    fu_progress_flag_from_string (const gchar *flag);

Converts a string to an progress flag.

#### Parameters

flag | a string, e.g. `guessed` |

#### Returns

enumerated value

Since: 1.7.0

### fu_progress_add_flag ()

    void
    fu_progress_add_flag (FuProgress *self,
                          FuProgressFlags flag);

Adds a flag.

#### Parameters

self | a FuProgress |
flag | an internal progress flag, e.g. `FU_PROGRESS_FLAG_GUESSED` |

Since: 1.7.0

### fu_progress_remove_flag ()

    void
    fu_progress_remove_flag (FuProgress *self,
                             FuProgressFlags flag);

Removes a flag.

#### Parameters

self | a FuProgress |
flag | an internal progress flag, e.g. `FU_PROGRESS_FLAG_GUESSED` |

Since: 1.7.0

### fu_progress_has_flag ()

    gboolean
    fu_progress_has_flag (FuProgress *self,
                          FuProgressFlags flag);

Tests for a flag.

#### Parameters

self | a FuProgress |
flag | an internal progress flag, e.g. `FU_PROGRESS_FLAG_GUESSED` |

Since: 1.7.0

### fu_progress_get_status ()

    FwupdStatus
    fu_progress_get_status (FuProgress *self);

Return the status of the progress, which is normally indirectly by `fu_progress_add_step()`.

#### Parameters

self | a FuProgress |

#### Returns

status

Since: 1.7.0

### fu_progress_set_status ()

    void
    fu_progress_set_status (FuProgress *self,
                            FwupdStatus status);

Sets the status of the progress.

#### Parameters

self | a FuProgress |
status | device status |

Since: 1.7.0

### fu_progress_set_percentage ()

    void
    fu_progress_set_percentage (FuProgress *self,
                                guint percentage);

Sets the progress percentage complete.

NOTE: this must be above what was previously set, or it will be rejected.

#### Parameters

self | a FuProgress |
percentage | value between 0% and 100% |

Since: 1.7.0

### fu_progress_set_percentage_full ()

    void
    fu_progress_set_percentage_full (FuProgress *self,
                                     gsize progress_done,
                                     gsize progress_total);

Sets the progress completion using the raw progress values.

#### Parameters

self | a FuDevice |
progress_done | the bytes already done |
progress_total | the total number of bytes |

Since: 1.7.0

### fu_progress_get_percentage ()

    guint
    fu_progress_get_percentage (FuProgress *self);

Get the last set progress percentage.

#### Parameters

self | a FuProgress |

#### Returns

The percentage value, or `G_MAXUINT` for error

Since: 1.7.0

### fu_progress_set_profile ()

    void
    fu_progress_set_profile (FuProgress *self,
                             gboolean profile);

This enables profiling of FuProgress. This may be useful in development, but be warned; enabling profiling makes FuProgress very slow.

#### Parameters

self | A FuProgress |
profile | if profiling should be enabled |

Since: 1.7.0

### fu_progress_reset ()

    void
    fu_progress_reset (FuProgress *self);

Resets the FuProgress object to unset

#### Parameters

self | A FuProgress |

Since: 1.7.0

### fu_progress_set_steps ()

    void
    fu_progress_set_steps (FuProgress *self,
                           guint step_max);

Sets the number of sub-tasks, i.e. how many times the `fu_progress_step_done()` function will be called in the loop.

The progress ID must be set `fu_progress_set_id()` before this method is used.

#### Parameters

self | A FuProgress |
step_max | The number of sub-tasks in this progress, can be 0 |

Since: 1.7.0

### fu_progress_get_steps ()

    guint
    fu_progress_get_steps (FuProgress *self);

Gets the number of sub-tasks, i.e. how many times the `fu_progress_step_done()` function will be called in the loop.

#### Parameters

self | A FuProgress |

#### Returns

number of sub-tasks in this progress

Since: 1.7.0

### fu_progress_add_step ()

    void
    fu_progress_add_step (FuProgress *self,
                          FwupdStatus status,
                          guint value);

This sets the step weighting, which you will want to do if one action will take a bigger chunk of time than another.

The progress ID must be set `fu_progress_set_id()` before this method is used.

#### Parameters

self | A FuProgress |
status | status value to use for this phase |
value | A step weighting variable argument array |

Since: 1.7.0

### fu_progress_finished ()

    void
    fu_progress_finished (FuProgress *self);

Called when the step_now sub-task wants to finish early and still complete.

#### Parameters

self | A FuProgress |

Since: 1.7.0

### fu_progress_step_done ()

    void
    fu_progress_step_done (FuProgress *self);

Called when the step_now sub-task has finished.

#### Parameters

self | A FuProgress |

Since: 1.7.0

### fu_progress_get_child ()

    FuProgress *
    fu_progress_get_child (FuProgress *self);

Monitor a child and proxy back up to the parent with the correct percentage.

#### Parameters

self | A FuProgress |

#### Returns

A new `FuProgress` or `NULL` for failure.

[transfer none]

Since: 1.7.0

### fu_progress_sleep ()

    void
    fu_progress_sleep (FuProgress *self,
                       guint delay_ms);

Sleeps, setting the device progress from 0..100% as time continues.

#### Parameters

self | a FuProgress |
delay_ms | the delay in milliseconds |

Since: 1.7.0

## Types and Values

### FU_TYPE_PROGRESS

    #define FU_TYPE_PROGRESS (fu_progress_get_type())

### struct FuProgressClass

    struct FuProgressClass {
    	GObjectClass parent_class;
    	/* signals */
    	void (*percentage_changed)(FuProgress *self, guint value);
    	void (*status_changed)(FuProgress *self, FwupdStatus status);
    };

### FuProgressFlags

    typedef guint64 FuProgressFlags;

The progress internal flags.

### FU_PROGRESS_FLAG_NONE

    #define FU_PROGRESS_FLAG_NONE (0)

No flags set.

Since: 1.7.0

### FU_PROGRESS_FLAG_UNKNOWN

    #define FU_PROGRESS_FLAG_UNKNOWN G_MAXUINT64

Unknown flag value.

Since: 1.7.0

### FU_PROGRESS_FLAG_GUESSED

    #define FU_PROGRESS_FLAG_GUESSED (1ull << 0)

The steps have not been measured on real hardware and have been guessed.

Since: 1.7.0

### FU_PROGRESS_FLAG_NO_PROFILE

    #define FU_PROGRESS_FLAG_NO_PROFILE (1ull << 1)

The steps cannot be accurate enough for a profile result.

Since: 1.7.0

### FuProgress

    typedef struct _FuProgress FuProgress;

Objects can use `fu_progress_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 `fu_progress_set_steps()` and then after each section is completed, the `fu_progress_step_done()` function should be called. This will automatically call `fu_progress_set_percentage()` with the correct values.

FuProgress 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 `fu_progress_get_child()` and then use the result in any sub-process. You should ensure that the child is not re-used without calling `fu_progress_step_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 parent updates.

static void _do_something(FuProgress *self) { // setup correct number of steps fu_progress_set_steps(self, 2);

// run a sub function _do_something_else1(fu_progress_get_child(self));

// this section done fu_progress_step_done(self);

// run another sub function _do_something_else2(fu_progress_get_child(self));

// this progress done (all complete) fu_progress_step_done(self); }

See also: [class`FuDevice` ]