FuFirmwareImage

FuFirmwareImage — a firmware image section

Functions

Types and Values

Description

An object that represents an image within the firmware file.

Functions

fu_firmware_image_new ()

FuFirmwareImage *
fu_firmware_image_new (GBytes *bytes);

Creates an empty firmware_image object.

Parameters

bytes

Optional GBytes

 

Returns

a FuFirmwareImage

Since: 1.3.1


fu_firmware_image_to_string ()

gchar *
fu_firmware_image_to_string (FuFirmwareImage *self);

This allows us to easily print the object.

Parameters

self

A FuFirmwareImage

 

Returns

a string value, or NULL for invalid.

Since: 1.3.1


fu_firmware_image_get_version ()

const gchar *
fu_firmware_image_get_version (FuFirmwareImage *self);

Gets an optional version that represents the firmware image.

Parameters

self

A FuFirmwareImage

 

Returns

a string, or NULL

Since: 1.3.4


fu_firmware_image_set_version ()

void
fu_firmware_image_set_version (FuFirmwareImage *self,
                               const gchar *version);

Sets an optional version that represents the firmware image.

Parameters

self

A FuFirmwareImage

 

version

A string version, or NULL.

[nullable]

Since: 1.3.4


fu_firmware_image_get_filename ()

const gchar *
fu_firmware_image_get_filename (FuFirmwareImage *self);

Gets an optional filename that represents the image source or destination.

Parameters

self

A FuFirmwareImage

 

Returns

a string, or NULL

Since: 1.5.0


fu_firmware_image_set_filename ()

void
fu_firmware_image_set_filename (FuFirmwareImage *self,
                                const gchar *filename);

Sets an optional filename that represents the image source or destination.

Parameters

self

A FuFirmwareImage

 

filename

A string filename, or NULL.

[nullable]

Since: 1.5.0


fu_firmware_image_get_id ()

const gchar *
fu_firmware_image_get_id (FuFirmwareImage *self);

Gets the image ID, typically set at construction.

Parameters

self

a FuPlugin

 

Returns

image ID, e.g. "config"

Since: 1.3.1


fu_firmware_image_set_id ()

void
fu_firmware_image_set_id (FuFirmwareImage *self,
                          const gchar *id);

Parameters

self

a FuPlugin

 

id

image ID, e.g. "config".

[nullable]

Since: 1.3.1


fu_firmware_image_get_addr ()

guint64
fu_firmware_image_get_addr (FuFirmwareImage *self);

Gets the base address of the image.

Parameters

self

a FuPlugin

 

Returns

integer

Since: 1.3.1


fu_firmware_image_set_addr ()

void
fu_firmware_image_set_addr (FuFirmwareImage *self,
                            guint64 addr);

Sets the base address of the image.

Parameters

self

a FuPlugin

 

addr

integer

 

Since: 1.3.1


fu_firmware_image_get_offset ()

guint64
fu_firmware_image_get_offset (FuFirmwareImage *self);

Gets the base offset of the image.

Parameters

self

a FuPlugin

 

Returns

integer

Since: 1.5.0


fu_firmware_image_set_offset ()

void
fu_firmware_image_set_offset (FuFirmwareImage *self,
                              guint64 offset);

Sets the base offset of the image.

Parameters

self

a FuPlugin

 

offset

integer

 

Since: 1.5.0


fu_firmware_image_get_idx ()

guint64
fu_firmware_image_get_idx (FuFirmwareImage *self);

Gets the index of the image which is used for ordering.

Parameters

self

a FuPlugin

 

Returns

integer

Since: 1.3.1


fu_firmware_image_set_idx ()

void
fu_firmware_image_set_idx (FuFirmwareImage *self,
                           guint64 idx);

Sets the index of the image which is used for ordering.

Parameters

self

a FuPlugin

 

idx

integer

 

Since: 1.3.1


fu_firmware_image_get_bytes ()

GBytes *
fu_firmware_image_get_bytes (FuFirmwareImage *self);

Gets the data set using fu_firmware_image_set_bytes().

This should only really be used by objects subclassing FuFirmwareImage as images are normally exported to a file using fu_firmware_image_write().

Parameters

self

a FuPlugin

 

Returns

a GBytes of the data, or NULL if the bytes is not set.

[transfer full]

Since: 1.5.0


fu_firmware_image_set_bytes ()

void
fu_firmware_image_set_bytes (FuFirmwareImage *self,
                             GBytes *bytes);

Sets the contents of the image if not created with fu_firmware_image_new().

Parameters

self

a FuPlugin

 

bytes

A GBytes

 

Since: 1.3.1


fu_firmware_image_add_chunk ()

void
fu_firmware_image_add_chunk (FuFirmwareImage *self,
                             FuChunk *chk);

Adds a chunk to the image.

Parameters

self

a FuFirmwareImage

 

chk

a FuChunk

 

Since: 1.5.6


fu_firmware_image_get_chunks ()

GPtrArray *
fu_firmware_image_get_chunks (FuFirmwareImage *self,
                              GError **error);

Gets the optional image chunks.

Parameters

self

a FuFirmwareImage

 

error

A GError, or NULL

 

Returns

chunk data, or NULL.

[transfer container][element-type FuChunk][nullable]

Since: 1.5.6


fu_firmware_image_get_checksum ()

gchar *
fu_firmware_image_get_checksum (FuFirmwareImage *self,
                                GChecksumType csum_kind,
                                GError **error);

Returns a checksum of the data.

Parameters

self

a FuPlugin

 

csum_kind

a GChecksumType, e.g. G_CHECKSUM_SHA256

 

error

A GError, or NULL

 

Returns

a checksum string, or NULL if the checksum is not available.

[transfer full]

Since: 1.5.5


fu_firmware_image_parse ()

gboolean
fu_firmware_image_parse (FuFirmwareImage *self,
                         GBytes *fw,
                         FwupdInstallFlags flags,
                         GError **error);

Parses a firmware image, typically checking image CRCs and/or headers.

Parameters

self

A FuFirmwareImage

 

fw

A GBytes

 

flags

some FwupdInstallFlags, e.g. FWUPD_INSTALL_FLAG_FORCE

 

error

A GError, or NULL

 

Returns

TRUE for success

Since: 1.5.0


fu_firmware_image_build ()

gboolean
fu_firmware_image_build (FuFirmwareImage *self,
                         XbNode *n,
                         GError **error);

Builds a firmware image from an XML manifest.

Parameters

self

A FuFirmwareImage

 

n

A XbNode

 

error

A GError, or NULL

 

Returns

TRUE for success

Since: 1.5.0


fu_firmware_image_write ()

GBytes *
fu_firmware_image_write (FuFirmwareImage *self,
                         GError **error);

Writes the image, which will try to call a superclassed ->write() function.

By default (and in most cases) this just provides the value set by the fu_firmware_image_set_bytes() function.

Parameters

self

a FuPlugin

 

error

A GError, or NULL

 

Returns

a GBytes of the bytes, or NULL if the bytes is not set.

[transfer full]

Since: 1.3.3


fu_firmware_image_write_chunk ()

GBytes *
fu_firmware_image_write_chunk (FuFirmwareImage *self,
                               guint64 address,
                               guint64 chunk_sz_max,
                               GError **error);

Gets a block of data from the image. If the contents of the image is smaller than the requested chunk size then the GBytes will be smaller than chunk_sz_max . Use fu_common_bytes_pad() if padding is required.

If the address is larger than the size of the image then an error is returned.

Parameters

self

a FuFirmwareImage

 

address

an address greater than dfu_element_get_address()

 

chunk_sz_max

the size of the new chunk

 

error

a GError, or NULL

 

Returns

a GBytes, or NULL.

[transfer full]

Since: 1.3.1

Types and Values

FU_TYPE_FIRMWARE_IMAGE

#define FU_TYPE_FIRMWARE_IMAGE (fu_firmware_image_get_type ())

struct FuFirmwareImageClass

struct FuFirmwareImageClass {
	GObjectClass		 parent_class;
	gboolean		 (*parse) (FuFirmwareImage *self,
						 GBytes			*fw,
						 FwupdInstallFlags	 flags,
						 GError			**error)
						 G_GNUC_WARN_UNUSED_RESULT;
	void			 (*to_string) (FuFirmwareImage *self,
						 guint			 idt,
						 GString		*str);
	GBytes			*(*write) (FuFirmwareImage *self,
						 GError			**error)
						 G_GNUC_WARN_UNUSED_RESULT;
	gboolean		 (*build) (FuFirmwareImage *self,
						 XbNode			*n,
						 GError			**error)
						 G_GNUC_WARN_UNUSED_RESULT;
	gchar			*(*get_checksum)(FuFirmwareImage *self,
						 GChecksumType		 csum_kind,
						 GError			**error)
						 G_GNUC_WARN_UNUSED_RESULT;
};

FU_FIRMWARE_IMAGE_ID_PAYLOAD

#define FU_FIRMWARE_IMAGE_ID_PAYLOAD		"payload"

FU_FIRMWARE_IMAGE_ID_SIGNATURE

#define FU_FIRMWARE_IMAGE_ID_SIGNATURE		"signature"

FU_FIRMWARE_IMAGE_ID_HEADER

#define FU_FIRMWARE_IMAGE_ID_HEADER		"header"

FuFirmwareImage

typedef struct _FuFirmwareImage FuFirmwareImage;