FuProgress

FuProgress

Functions

Types and Values

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: [classFuDevice ]