DfuFirmware

DfuFirmware — Object representing a DFU or DfuSe firmware file

Functions

Types and Values

Description

This object allows reading and writing firmware files either in raw, DFU or DfuSe formats.

A DfuFirmware can be made up of several DfuImages, although typically there is only one.

See also: DfuImage

Functions

dfu_firmware_new ()

DfuFirmware *
dfu_firmware_new (void);

Creates a new DFU firmware object.

Returns

a new DfuFirmware

Since: 0.5.4


dfu_firmware_format_to_string ()

const gchar *
dfu_firmware_format_to_string (DfuFirmwareFormat format);

Returns a string representaiton of the format.

Parameters

Returns

NULL terminated string, or NULL for invalid

Since: 0.5.4


dfu_firmware_format_from_string ()

DfuFirmwareFormat
dfu_firmware_format_from_string (const gchar *format);

Returns an enumerated version of the format.

Parameters

format

a format string, e.g. dfuse

 

Since: 0.7.3


dfu_firmware_get_image ()

DfuImage *
dfu_firmware_get_image (DfuFirmware *firmware,
                        guint8 alt_setting);

Gets an image from the firmware file.

Parameters

firmware

a DfuFirmware

 

alt_setting

an alternative setting, typically 0x00

 

Returns

a DfuImage, or NULL for not found.

[transfer none]

Since: 0.5.4


dfu_firmware_get_image_by_name ()

DfuImage *
dfu_firmware_get_image_by_name (DfuFirmware *firmware,
                                const gchar *name);

Gets an image from the firmware file.

Parameters

firmware

a DfuFirmware

 

name

an alternative setting name

 

Returns

a DfuImage, or NULL for not found.

[transfer none]

Since: 0.5.4


dfu_firmware_get_image_default ()

DfuImage *
dfu_firmware_get_image_default (DfuFirmware *firmware);

Gets the default image from the firmware file.

Parameters

firmware

a DfuFirmware

 

Returns

a DfuImage, or NULL for not found.

[transfer none]

Since: 0.5.4


dfu_firmware_get_images ()

GPtrArray *
dfu_firmware_get_images (DfuFirmware *firmware);

Gets all the images contained in this firmware file.

Parameters

firmware

a DfuFirmware

 

Returns

list of images.

[transfer none][element-type DfuImage]

Since: 0.5.4


dfu_firmware_get_vid ()

guint16
dfu_firmware_get_vid (DfuFirmware *firmware);

Gets the vendor ID.

Parameters

firmware

a DfuFirmware

 

Returns

a vendor ID, or 0xffff for unset

Since: 0.5.4


dfu_firmware_get_pid ()

guint16
dfu_firmware_get_pid (DfuFirmware *firmware);

Gets the product ID.

Parameters

firmware

a DfuFirmware

 

Returns

a product ID, or 0xffff for unset

Since: 0.5.4


dfu_firmware_get_release ()

guint16
dfu_firmware_get_release (DfuFirmware *firmware);

Gets the device ID.

Parameters

firmware

a DfuFirmware

 

Returns

a device ID, or 0xffff for unset

Since: 0.5.4


dfu_firmware_get_format ()

guint16
dfu_firmware_get_format (DfuFirmware *firmware);

Gets the DFU version.

Parameters

firmware

a DfuFirmware

 

Returns

a version, or 0x0 for unset

Since: 0.5.4


dfu_firmware_get_size ()

guint32
dfu_firmware_get_size (DfuFirmware *firmware);

Gets the size of all the images in the firmware.

This only returns actual data that would be sent to the device and does not include any padding.

Parameters

firmware

a DfuFirmware

 

Returns

a integer value, or 0 if there are no images.

Since: 0.5.4


dfu_firmware_get_cipher_kind ()

DfuCipherKind
dfu_firmware_get_cipher_kind (DfuFirmware *firmware);

Returns the kind of cipher used by the firmware file.

NOTE: this value is based on a heuristic, and may not be accurate. The value DFU_CIPHER_KIND_NONE will be returned when the cipher is not recognised.

Parameters

firmware

a DfuFirmware

 

Returns

NULL terminated string, or NULL for invalid

Since: 0.5.4


dfu_firmware_add_image ()

void
dfu_firmware_add_image (DfuFirmware *firmware,
                        DfuImage *image);

Adds an image to the list of images.

Parameters

firmware

a DfuFirmware

 

image

a DfuImage

 

Since: 0.5.4


dfu_firmware_set_vid ()

void
dfu_firmware_set_vid (DfuFirmware *firmware,
                      guint16 vid);

Sets the vendor ID.

Parameters

firmware

a DfuFirmware

 

vid

vendor ID, or 0xffff for unset

 

Since: 0.5.4


dfu_firmware_set_pid ()

void
dfu_firmware_set_pid (DfuFirmware *firmware,
                      guint16 pid);

Sets the product ID.

Parameters

firmware

a DfuFirmware

 

pid

product ID, or 0xffff for unset

 

Since: 0.5.4


dfu_firmware_set_release ()

void
dfu_firmware_set_release (DfuFirmware *firmware,
                          guint16 release);

Sets the device ID.

Parameters

firmware

a DfuFirmware

 

release

device ID, or 0xffff for unset

 

Since: 0.5.4


dfu_firmware_set_format ()

void
dfu_firmware_set_format (DfuFirmware *firmware,
                         DfuFirmwareFormat format);

Sets the DFU version in BCD format.

Parameters

firmware

a DfuFirmware

 

format

a DfuFirmwareFormat, e.g. DFU_FIRMWARE_FORMAT_DFUSE

 

Since: 0.5.4


dfu_firmware_set_cipher_kind ()

void
dfu_firmware_set_cipher_kind (DfuFirmware *firmware,
                              DfuCipherKind cipher_kind);

Sets the kind of cipher used by the firmware file.

Parameters

firmware

a DfuFirmware

 

cipher_kind

a DfuCipherKind, e.g. DFU_CIPHER_KIND_XTEA

 

Since: 0.6.3


dfu_firmware_parse_data ()

gboolean
dfu_firmware_parse_data (DfuFirmware *firmware,
                         GBytes *bytes,
                         DfuFirmwareParseFlags flags,
                         GError **error);

Parses firmware data which may have an optional DFU suffix.

Parameters

firmware

a DfuFirmware

 

bytes

raw firmware data

 

flags

optional flags, e.g. DFU_FIRMWARE_PARSE_FLAG_NO_CRC_TEST

 

error

a GError, or NULL

 

Returns

TRUE for success

Since: 0.5.4


dfu_firmware_parse_file ()

gboolean
dfu_firmware_parse_file (DfuFirmware *firmware,
                         GFile *file,
                         DfuFirmwareParseFlags flags,
                         GCancellable *cancellable,
                         GError **error);

Parses a DFU firmware, which may contain an optional footer.

Parameters

firmware

a DfuFirmware

 

file

a GFile to load and parse

 

flags

optional flags, e.g. DFU_FIRMWARE_PARSE_FLAG_NO_CRC_TEST

 

cancellable

a GCancellable, or NULL

 

error

a GError, or NULL

 

Returns

TRUE for success

Since: 0.5.4


dfu_firmware_write_data ()

GBytes *
dfu_firmware_write_data (DfuFirmware *firmware,
                         GError **error);

Writes DFU data to a data blob with a DFU-specific footer.

Parameters

firmware

a DfuFirmware

 

error

a GError, or NULL

 

Returns

firmware data.

[transfer none]

Since: 0.5.4


dfu_firmware_write_file ()

gboolean
dfu_firmware_write_file (DfuFirmware *firmware,
                         GFile *file,
                         GCancellable *cancellable,
                         GError **error);

Writes a DFU firmware with the optional footer.

Parameters

firmware

a DfuFirmware

 

file

a GFile

 

cancellable

a GCancellable, or NULL

 

error

a GError, or NULL

 

Returns

TRUE for success

Since: 0.5.4


dfu_firmware_to_string ()

gchar *
dfu_firmware_to_string (DfuFirmware *firmware);

Returns a string representaiton of the object.

Parameters

firmware

a DfuFirmware

 

Returns

NULL terminated string, or NULL for invalid

Since: 0.5.4


dfu_firmware_get_metadata_table ()

GHashTable *
dfu_firmware_get_metadata_table (DfuFirmware *firmware);

Gets all metadata from the store.

Parameters

firmware

a DfuFirmware

 

Returns

the metadata hash table.

[transfer none]

Since: 0.6.3


dfu_firmware_get_metadata ()

const gchar *
dfu_firmware_get_metadata (DfuFirmware *firmware,
                           const gchar *key);

Gets metadata from the store with a specific key.

Parameters

firmware

a DfuFirmware

 

key

metadata string key

 

Returns

the metadata value, or NULL for unset

Since: 0.5.4


dfu_firmware_set_metadata ()

void
dfu_firmware_set_metadata (DfuFirmware *firmware,
                           const gchar *key,
                           const gchar *value);

Sets a metadata value with a specific key.

Parameters

firmware

a DfuFirmware

 

key

metadata string key

 

value

metadata string value

 

Since: 0.5.4


dfu_firmware_remove_metadata ()

void
dfu_firmware_remove_metadata (DfuFirmware *firmware,
                              const gchar *key);

Removes a metadata item from the store

Parameters

firmware

a DfuFirmware

 

key

metadata string key

 

Since: 0.5.4

Types and Values

DFU_TYPE_FIRMWARE

#define DFU_TYPE_FIRMWARE (dfu_firmware_get_type ())

struct DfuFirmwareClass

struct DfuFirmwareClass {
	GObjectClass		 parent_class;
};

enum DfuFirmwareParseFlags

The optional flags used for parsing.

Members

DFU_FIRMWARE_PARSE_FLAG_NONE

No flags set

 

DFU_FIRMWARE_PARSE_FLAG_NO_CRC_TEST

Do not verify the CRC

 

DFU_FIRMWARE_PARSE_FLAG_NO_VERSION_TEST

Do not verify the DFU version

 

DFU_FIRMWARE_PARSE_FLAG_NO_METADATA

Do not read the metadata table

 

enum DfuFirmwareFormat

The known versions of the DFU standard in BCD format.

Members

DFU_FIRMWARE_FORMAT_UNKNOWN

Format unknown

 

DFU_FIRMWARE_FORMAT_RAW

Raw format

 

DFU_FIRMWARE_FORMAT_DFU

DFU footer

 

DFU_FIRMWARE_FORMAT_DFUSE

DfuSe header

 

DFU_FIRMWARE_FORMAT_INTEL_HEX

Intel HEX

 

DFU_FIRMWARE_FORMAT_ELF

ELF

 

DfuFirmware

typedef struct _DfuFirmware DfuFirmware;