FuFirmware: fwupd Reference Manual

FuFirmware

FuFirmware — a firmware file

Functions

FuFirmware *	fu_firmware_new ()
FuFirmware *	fu_firmware_new_from_bytes ()
gchar *	fu_firmware_to_string ()
const gchar *	fu_firmware_get_version ()
void	fu_firmware_set_version ()
gboolean	fu_firmware_tokenize ()
gboolean	fu_firmware_parse ()
gboolean	fu_firmware_parse_file ()
gboolean	fu_firmware_parse_full ()
GBytes *	fu_firmware_write ()
gboolean	fu_firmware_write_file ()
void	fu_firmware_add_image ()
GPtrArray *	fu_firmware_get_images ()
FuFirmwareImage *	fu_firmware_get_image_by_id ()
GBytes *	fu_firmware_get_image_by_id_bytes ()
FuFirmwareImage *	fu_firmware_get_image_by_idx ()
GBytes *	fu_firmware_get_image_by_idx_bytes ()
FuFirmwareImage *	fu_firmware_get_image_default ()
GBytes *	fu_firmware_get_image_default_bytes ()

Types and Values

#define	FU_TYPE_FIRMWARE
struct	FuFirmwareClass
	FuFirmware

Description

An object that represents a firmware file. See also: FuDfuFirmware, FuIhexFirmware, FuSrecFirmware

Functions

fu_firmware_new ()

FuFirmware *
fu_firmware_new (void);

Creates an empty firmware object.

Returns

a FuFirmware

Since: 1.3.1

fu_firmware_new_from_bytes ()

FuFirmware *
fu_firmware_new_from_bytes (GBytes *fw);

Creates a firmware object with the provided image set as default.

Parameters

A GBytes image

Returns

a FuFirmware

Since: 1.3.1

fu_firmware_to_string ()

gchar *
fu_firmware_to_string (FuFirmware *self);

This allows us to easily print the object.

Parameters

self

A FuFirmware

Returns

a string value, or NULL for invalid.

Since: 1.3.1

fu_firmware_get_version ()

const gchar *
fu_firmware_get_version (FuFirmware *self);

Gets an optional version that represents the firmware.

Parameters

self

A FuFirmware

Returns

a string, or NULL

Since: 1.3.3

fu_firmware_set_version ()

void
fu_firmware_set_version (FuFirmware *self,
                         const gchar *version);

Sets an optional version that represents the firmware.

Parameters

self	A FuFirmware
version	A string version, or `NULL`

Since: 1.3.3

fu_firmware_tokenize ()

gboolean
fu_firmware_tokenize (FuFirmware *self,
                      GBytes *fw,
                      FwupdInstallFlags flags,
                      GError **error);

Tokenizes a firmware, typically breaking the firmware into records.

Records can be enumerated using subclass-specific functionality, for example using fu_srec_firmware_get_records().

Parameters

self	A FuFirmware
fw	A GBytes
flags	some FwupdInstallFlags, e.g. `FWUPD_INSTALL_FLAG_FORCE`
error	A GError, or `NULL`

Returns

TRUE for success

Since: 1.3.2

fu_firmware_parse ()

gboolean
fu_firmware_parse (FuFirmware *self,
                   GBytes *fw,
                   FwupdInstallFlags flags,
                   GError **error);

Parses a firmware, typically breaking the firmware into images.

Parameters

self	A FuFirmware
fw	A GBytes
flags	some FwupdInstallFlags, e.g. `FWUPD_INSTALL_FLAG_FORCE`
error	A GError, or `NULL`

Returns

TRUE for success

Since: 1.3.1

fu_firmware_parse_file ()

gboolean
fu_firmware_parse_file (FuFirmware *self,
                        GFile *file,
                        FwupdInstallFlags flags,
                        GError **error);

Parses a firmware file, typically breaking the firmware into images.

Parameters

self	A FuFirmware
file	A GFile
flags	some FwupdInstallFlags, e.g. `FWUPD_INSTALL_FLAG_FORCE`
error	A GError, or `NULL`

Returns

TRUE for success

Since: 1.3.3

fu_firmware_parse_full ()

gboolean
fu_firmware_parse_full (FuFirmware *self,
                        GBytes *fw,
                        guint64 addr_start,
                        guint64 addr_end,
                        FwupdInstallFlags flags,
                        GError **error);

Parses a firmware, typically breaking the firmware into images.

Parameters

self	A FuFirmware
fw	A GBytes
addr_start	Start address, useful for ignoring a bootloader
addr_end	End address, useful for ignoring config bytes
flags	some FwupdInstallFlags, e.g. `FWUPD_INSTALL_FLAG_FORCE`
error	A GError, or `NULL`

Returns

TRUE for success

Since: 1.3.1

fu_firmware_write ()

GBytes *
fu_firmware_write (FuFirmware *self,
                   GError **error);

Writes a firmware, typically packing the images into a binary blob.

Parameters

self	A FuFirmware
error	A GError, or `NULL`

Returns

a GBytes.

[transfer full]

Since: 1.3.1

fu_firmware_write_file ()

gboolean
fu_firmware_write_file (FuFirmware *self,
                        GFile *file,
                        GError **error);

Writes a firmware, typically packing the images into a binary blob.

Parameters

self	A FuFirmware
file	A GFile
error	A GError, or `NULL`

Returns

TRUE for success

Since: 1.3.3

fu_firmware_add_image ()

void
fu_firmware_add_image (FuFirmware *self,
                       FuFirmwareImage *img);

Adds an image to the firmware.

If an image with the same ID is already present it is replaced.

Parameters

self	a FuPlugin
img	A FuFirmwareImage

Since: 1.3.1

fu_firmware_get_images ()

GPtrArray *
fu_firmware_get_images (FuFirmware *self);

Returns all the images in the firmware.

Parameters

self

a FuFirmware

Returns

images.

[transfer container][element-type FuFirmwareImage]

Since: 1.3.1

fu_firmware_get_image_by_id ()

FuFirmwareImage *
fu_firmware_get_image_by_id (FuFirmware *self,
                             const gchar *id,
                             GError **error);

Gets the firmware image using the image ID.

Parameters

self	a FuPlugin
id	image ID, e.g. "config".	[nullable]
error	A GError, or `NULL`

Returns

a FuFirmwareImage, or NULL if the image is not found.

[transfer full]

Since: 1.3.1

fu_firmware_get_image_by_id_bytes ()

GBytes *
fu_firmware_get_image_by_id_bytes (FuFirmware *self,
                                   const gchar *id,
                                   GError **error);

Gets the firmware image bytes using the image ID.

Parameters

self	a FuPlugin
id	image ID, e.g. "config".	[nullable]
error	A GError, or `NULL`

Returns

a GBytes of a FuFirmwareImage, or NULL if the image is not found.

[transfer full]

Since: 1.3.1

fu_firmware_get_image_by_idx ()

FuFirmwareImage *
fu_firmware_get_image_by_idx (FuFirmware *self,
                              guint64 idx,
                              GError **error);

Gets the firmware image using the image index.

Parameters

self	a FuPlugin
idx	image index
error	A GError, or `NULL`

Returns

a FuFirmwareImage, or NULL if the image is not found.

[transfer full]

Since: 1.3.1

fu_firmware_get_image_by_idx_bytes ()

GBytes *
fu_firmware_get_image_by_idx_bytes (FuFirmware *self,
                                    guint64 idx,
                                    GError **error);

Gets the firmware image bytes using the image index.

Parameters

self	a FuPlugin
idx	image index
error	A GError, or `NULL`

Returns

a GBytes of a FuFirmwareImage, or NULL if the image is not found.

[transfer full]

Since: 1.3.1

fu_firmware_get_image_default ()

FuFirmwareImage *
fu_firmware_get_image_default (FuFirmware *self,
                               GError **error);

Gets the default firmware image.

NOTE: If the firmware has multiple images included then fu_firmware_get_image_by_id() or fu_firmware_get_image_by_idx() must be used rather than this function.

Parameters

self	a FuPlugin
error	A GError, or `NULL`

Returns

a FuFirmwareImage, or NULL if the image is not found.

[transfer full]

Since: 1.3.1

fu_firmware_get_image_default_bytes ()

GBytes *
fu_firmware_get_image_default_bytes (FuFirmware *self,
                                     GError **error);

Gets the default firmware image.

Parameters

self	a FuPlugin
error	A GError, or `NULL`

Returns

a GBytes of the image, or NULL if the image is not found.

[transfer full]

Since: 1.3.1

Types and Values

FU_TYPE_FIRMWARE

#define FU_TYPE_FIRMWARE (fu_firmware_get_type ())

struct FuFirmwareClass

struct FuFirmwareClass {
	GObjectClass		 parent_class;
	gboolean		 (*parse)		(FuFirmware *self,
							 GBytes		*fw,
							 guint64	 addr_start,
							 guint64	 addr_end,
							 FwupdInstallFlags flags,
							 GError		**error);
	GBytes			*(*write)		(FuFirmware *self,
							 GError		**error);
	void			 (*to_string)		(FuFirmware *self,
							 guint		 indent,
							 GString *str);
	gboolean		 (*tokenize)		(FuFirmware *self,
							 GBytes		*fw,
							 FwupdInstallFlags flags,
							 GError		**error);
};

FuFirmware

typedef struct _FuFirmware FuFirmware;