## DfuFirmware DfuFirmware — Object representing a DFU or DfuSe firmware file |

## Functions

DfuFirmware * | dfu_firmware_new ()
const gchar * | dfu_firmware_format_to_string ()
DfuFirmwareFormat | dfu_firmware_format_from_string ()
DfuImage * | dfu_firmware_get_image ()
DfuImage * | dfu_firmware_get_image_by_name ()
DfuImage * | dfu_firmware_get_image_default ()
GPtrArray * | dfu_firmware_get_images ()
guint16 | dfu_firmware_get_vid ()
guint16 | dfu_firmware_get_pid ()
guint16 | dfu_firmware_get_release ()
guint16 | dfu_firmware_get_format ()
guint32 | dfu_firmware_get_size ()
DfuCipherKind | dfu_firmware_get_cipher_kind ()
void | dfu_firmware_add_image ()
void | dfu_firmware_set_vid ()
void | dfu_firmware_set_pid ()
void | dfu_firmware_set_release ()
void | dfu_firmware_set_format ()
void | dfu_firmware_set_cipher_kind ()
gboolean | dfu_firmware_parse_data ()
gboolean | dfu_firmware_parse_file ()
GBytes * | dfu_firmware_write_data ()
gboolean | dfu_firmware_write_file ()
gchar * | dfu_firmware_to_string ()
GHashTable * | dfu_firmware_get_metadata_table ()
const gchar * | dfu_firmware_get_metadata ()
void | dfu_firmware_set_metadata ()
void | dfu_firmware_remove_metadata ()

## Types and Values

#define | DFU_TYPE_FIRMWARE
struct | DfuFirmwareClass
enum | DfuFirmwareParseFlags
enum | DfuFirmwareFormat
| DfuFirmware

## 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

format | a DfuFirmwareFormat, e.g. `DFU_FIRMWARE_FORMAT_DFU` |

#### 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` |

#### Returns

a DfuFirmwareFormat, e.g. `DFU_FIRMWARE_FORMAT_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;