DfuDevice: libdfu Reference Manual

DfuDevice

DfuDevice — Object representing a DFU-capable device

Functions

DfuDevice *	dfu_device_new ()
gboolean	dfu_device_open ()
gboolean	dfu_device_close ()
const gchar *	dfu_device_get_platform_id ()
GPtrArray *	dfu_device_get_targets ()
DfuTarget *	dfu_device_get_target_by_alt_setting ()
DfuTarget *	dfu_device_get_target_by_alt_name ()
const gchar *	dfu_device_get_display_name ()
const gchar *	dfu_device_get_serial_number ()
guint16	dfu_device_get_runtime_vid ()
guint16	dfu_device_get_runtime_pid ()
guint16	dfu_device_get_runtime_release ()
gboolean	dfu_device_reset ()
gboolean	dfu_device_attach ()
gboolean	dfu_device_wait_for_replug ()
DfuFirmware *	dfu_device_upload ()
gboolean	dfu_device_download ()
gboolean	dfu_device_refresh ()
gboolean	dfu_device_detach ()
gboolean	dfu_device_abort ()
gboolean	dfu_device_clear_status ()
guint8	dfu_device_get_interface ()
DfuMode	dfu_device_get_mode ()
DfuState	dfu_device_get_state ()
DfuStatus	dfu_device_get_status ()
guint16	dfu_device_get_transfer_size ()
guint16	dfu_device_get_version ()
guint	dfu_device_get_timeout ()
gboolean	dfu_device_can_upload ()
gboolean	dfu_device_can_download ()
gboolean	dfu_device_has_attribute ()
gboolean	dfu_device_has_quirk ()
void	dfu_device_set_transfer_size ()
void	dfu_device_set_timeout ()

Types and Values

#define	DFU_TYPE_DEVICE
enum	DfuDeviceOpenFlags
enum	DfuDeviceQuirks
enum	DfuDeviceAttributes
struct	DfuDeviceClass
	DfuDevice

Description

This object allows two things:

Downloading from the host to the device, optionally with verification using a DFU or DfuSe firmware file.
Uploading from the device to the host to a DFU or DfuSe firmware file. The file format is chosen automatically, with DfuSe being chosen if the device contains more than one target.

Functions

dfu_device_new ()

DfuDevice *
dfu_device_new (GUsbDevice *dev);

Creates a new DFU device object.

Parameters

dev

A GUsbDevice

Returns

a new DfuDevice, or NULL if dev was not DFU-capable

Since: 0.5.4

dfu_device_open ()

gboolean
dfu_device_open (DfuDevice *device,
                 DfuDeviceOpenFlags flags,
                 GCancellable *cancellable,
                 GError **error);

Opens a DFU-capable device.

Parameters

device	a DfuDevice
flags	DfuDeviceOpenFlags, e.g. `DFU_DEVICE_OPEN_FLAG_NONE`
cancellable	a GCancellable, or `NULL`
error	a GError, or `NULL`

Returns

TRUE for success

Since: 0.5.4

dfu_device_close ()

gboolean
dfu_device_close (DfuDevice *device,
                  GError **error);

Closes a DFU device.

Parameters

device	a DfuDevice
error	a GError, or `NULL`

Returns

TRUE for success

Since: 0.5.4

dfu_device_get_platform_id ()

const gchar *
dfu_device_get_platform_id (DfuDevice *device);

Gets the platform ID which normally corresponds to the port in some way.

Parameters

device

a DfuDevice

Returns

string or NULL

Since: 0.5.4

dfu_device_get_targets ()

GPtrArray *
dfu_device_get_targets (DfuDevice *device);

Gets all the targets for this device.

Parameters

device

a DfuDevice

Returns

DfuTarget, or NULL.

[transfer none][element-type DfuTarget]

Since: 0.5.4

dfu_device_get_target_by_alt_setting ()

DfuTarget *
dfu_device_get_target_by_alt_setting (DfuDevice *device,
                                      guint8 alt_setting,
                                      GError **error);

Gets a target with a specific alternative setting.

Parameters

device	a DfuDevice
alt_setting	the setting used to find
error	a GError, or `NULL`

Returns

a DfuTarget, or NULL.

[transfer full]

Since: 0.5.4

dfu_device_get_target_by_alt_name ()

DfuTarget *
dfu_device_get_target_by_alt_name (DfuDevice *device,
                                   const gchar *alt_name,
                                   GError **error);

Gets a target with a specific alternative name.

Parameters

device	a DfuDevice
alt_name	the name used to find
error	a GError, or `NULL`

Returns

a DfuTarget, or NULL.

[transfer full]

Since: 0.5.4

dfu_device_get_display_name ()

const gchar *
dfu_device_get_display_name (DfuDevice *device);

Gets the display name to use for the device.

Parameters

device

a DfuDevice

Returns

string or NULL for unset

Since: 0.5.4

dfu_device_get_serial_number ()

const gchar *
dfu_device_get_serial_number (DfuDevice *device);

Gets the serial number for the device.

Parameters

device

a DfuDevice

Returns

string or NULL for unset

Since: 0.7.3

dfu_device_get_runtime_vid ()

guint16
dfu_device_get_runtime_vid (DfuDevice *device);

Gets the runtime vendor ID.

Parameters

device

a DfuDevice

Returns

vendor ID, or 0xffff for unknown

Since: 0.5.4

dfu_device_get_runtime_pid ()

guint16
dfu_device_get_runtime_pid (DfuDevice *device);

Gets the runtime product ID.

Parameters

device

a DfuDevice

Returns

product ID, or 0xffff for unknown

Since: 0.5.4

dfu_device_get_runtime_release ()

guint16
dfu_device_get_runtime_release (DfuDevice *device);

Gets the runtime release number in BCD format.

Parameters

device

a DfuDevice

Returns

release number, or 0xffff for unknown

Since: 0.5.4

dfu_device_reset ()

gboolean
dfu_device_reset (DfuDevice *device,
                  GError **error);

Resets the USB device.

Parameters

device	a DfuDevice
error	a GError, or `NULL`

Returns

TRUE for success

Since: 0.5.4

dfu_device_attach ()

gboolean
dfu_device_attach (DfuDevice *device,
                   GError **error);

Move device from DFU mode to runtime.

Parameters

device	a DfuDevice
error	a GError, or `NULL`

Returns

TRUE for success

Since: 0.5.4

dfu_device_wait_for_replug ()

gboolean
dfu_device_wait_for_replug (DfuDevice *device,
                            guint timeout,
                            GCancellable *cancellable,
                            GError **error);

Waits for a DFU device to disconnect and reconnect. This does rely on a DfuContext being set up before this is called.

Parameters

device	a DfuDevice
timeout	the maximum amount of time to wait
cancellable	a GCancellable, or `NULL`
error	a GError, or `NULL`

Returns

TRUE for success

Since: 0.5.4

dfu_device_upload ()

DfuFirmware *
dfu_device_upload (DfuDevice *device,
                   DfuTargetTransferFlags flags,
                   GCancellable *cancellable,
                   GError **error);

Uploads firmware from the target to the host.

Parameters

device	a DfuDevice
flags	flags to use, e.g. `DFU_TARGET_TRANSFER_FLAG_VERIFY`
cancellable	a GCancellable, or `NULL`
error	a GError, or `NULL`

Returns

the uploaded firmware, or NULL for error.

[transfer full]

Since: 0.5.4

dfu_device_download ()

gboolean
dfu_device_download (DfuDevice *device,
                     DfuFirmware *firmware,
                     DfuTargetTransferFlags flags,
                     GCancellable *cancellable,
                     GError **error);

Downloads firmware from the host to the target, optionally verifying the transfer.

Parameters

device	a DfuDevice
firmware	a DfuFirmware
flags	flags to use, e.g. `DFU_TARGET_TRANSFER_FLAG_VERIFY`
cancellable	a GCancellable, or `NULL`
error	a GError, or `NULL`

Returns

TRUE for success

Since: 0.5.4

dfu_device_refresh ()

gboolean
dfu_device_refresh (DfuDevice *device,
                    GCancellable *cancellable,
                    GError **error);

Refreshes the cached properties on the DFU device.

Parameters

device	a DfuDevice
cancellable	a GCancellable, or `NULL`
error	a GError, or `NULL`

Returns

TRUE for success

Since: 0.5.4

dfu_device_detach ()

gboolean
dfu_device_detach (DfuDevice *device,
                   GCancellable *cancellable,
                   GError **error);

Detaches the device putting it into DFU-mode.

Parameters

device	a DfuDevice
cancellable	a GCancellable, or `NULL`
error	a GError, or `NULL`

Returns

TRUE for success

Since: 0.5.4

dfu_device_abort ()

gboolean
dfu_device_abort (DfuDevice *device,
                  GCancellable *cancellable,
                  GError **error);

Aborts any upload or download in progress.

Parameters

device	a DfuDevice
cancellable	a GCancellable, or `NULL`
error	a GError, or `NULL`

Returns

TRUE for success

Since: 0.5.4

dfu_device_clear_status ()

gboolean
dfu_device_clear_status (DfuDevice *device,
                         GCancellable *cancellable,
                         GError **error);

Clears any error status on the DFU device.

Parameters

device	a DfuDevice
cancellable	a GCancellable, or `NULL`
error	a GError, or `NULL`

Returns

TRUE for success

Since: 0.5.4

dfu_device_get_interface ()

guint8
dfu_device_get_interface (DfuDevice *device);

Gets the interface number.

Parameters

device

a DfuDevice

Since: 0.5.4

dfu_device_get_mode ()

DfuMode
dfu_device_get_mode (DfuDevice *device);

Gets the device mode.

Parameters

device

a GUsbDevice

Returns

enumerated mode, e.g. DFU_MODE_RUNTIME

Since: 0.5.4

dfu_device_get_state ()

DfuState
dfu_device_get_state (DfuDevice *device);

Gets the device state.

Parameters

device

a GUsbDevice

Returns

enumerated state, e.g. DFU_STATE_DFU_UPLOAD_IDLE

Since: 0.5.4

dfu_device_get_status ()

DfuStatus
dfu_device_get_status (DfuDevice *device);

Gets the device status.

Parameters

device

a GUsbDevice

Returns

enumerated status, e.g. DFU_STATUS_ERR_ADDRESS

Since: 0.5.4

dfu_device_get_transfer_size ()

guint16
dfu_device_get_transfer_size (DfuDevice *device);

Gets the transfer size in bytes.

Parameters

device

a GUsbDevice

Returns

packet size, or 0 for unknown

Since: 0.5.4

dfu_device_get_version ()

guint16
dfu_device_get_version (DfuDevice *device);

Gets the DFU specification version supported by the device.

Parameters

device

a GUsbDevice

Returns

integer, or 0 for unknown, e.g. DFU_VERSION_DFU_1_1

Since: 0.7.2

dfu_device_get_timeout ()

guint
dfu_device_get_timeout (DfuDevice *device);

Gets the device timeout.

Parameters

device

a GUsbDevice

Returns

enumerated timeout in ms

Since: 0.5.4

dfu_device_can_upload ()

gboolean
dfu_device_can_upload (DfuDevice *device);

Gets if the device can upload.

Parameters

device

a GUsbDevice

Returns

TRUE if the device can upload from device to host

Since: 0.5.4

dfu_device_can_download ()

gboolean
dfu_device_can_download (DfuDevice *device);

Gets if the device can download.

Parameters

device

a GUsbDevice

Returns

TRUE if the device can download from host to device

Since: 0.5.4

dfu_device_has_attribute ()

gboolean
dfu_device_has_attribute (DfuDevice *device,
                          DfuDeviceAttributes attribute);

Returns if an attribute set for the device.

[skip]

Parameters

device	A DfuDevice
attribute	A DfuDeviceAttributes, e.g. `DFU_DEVICE_ATTRIBUTE_CAN_DOWNLOAD`

Returns

TRUE if the attribute is set

Since: 0.5.4

dfu_device_has_quirk ()

gboolean
dfu_device_has_quirk (DfuDevice *device,
                      DfuDeviceQuirks quirk);

Returns if a device has a specific quirk

[skip]

Parameters

device	A DfuDevice
quirk	A DfuDeviceQuirks

Returns

TRUE if the device has this quirk

Since: 0.5.4

dfu_device_set_transfer_size ()

void
dfu_device_set_transfer_size (DfuDevice *device,
                              guint16 transfer_size);

Sets the transfer size in bytes.

Parameters

device	a GUsbDevice
transfer_size	maximum packet size

Since: 0.5.4

dfu_device_set_timeout ()

void
dfu_device_set_timeout (DfuDevice *device,
                        guint timeout_ms);

Sets the USB timeout to use when contacting the USB device.

Parameters

device	a DfuDevice
timeout_ms	the timeout in ms

Since: 0.5.4

Types and Values

DFU_TYPE_DEVICE

#define DFU_TYPE_DEVICE (dfu_device_get_type ())

enum DfuDeviceOpenFlags

The optional flags used for opening the target.

Members

DFU_DEVICE_OPEN_FLAG_NONE	No flags set
DFU_DEVICE_OPEN_FLAG_NO_AUTO_REFRESH	Do not do the initial GET_STATUS

enum DfuDeviceQuirks

The workarounds for different devices.

Members

DFU_DEVICE_QUIRK_NONE	No device quirks
DFU_DEVICE_QUIRK_IGNORE_POLLTIMEOUT	Ignore the device download timeout
DFU_DEVICE_QUIRK_FORCE_DFU_MODE	Force DFU mode
DFU_DEVICE_QUIRK_IGNORE_INVALID_VERSION	Ignore invalid version numbers
DFU_DEVICE_QUIRK_USE_PROTOCOL_ZERO	Fix up the protocol number
DFU_DEVICE_QUIRK_NO_PID_CHANGE	Accept the same VID:PID when changing modes
DFU_DEVICE_QUIRK_NO_GET_STATUS_UPLOAD	Do not do GetStatus when uploading
DFU_DEVICE_QUIRK_NO_DFU_RUNTIME	No DFU runtime interface is provided
DFU_DEVICE_QUIRK_ATTACH_UPLOAD_DOWNLOAD	An upload or download is required for attach
DFU_DEVICE_QUIRK_IGNORE_RUNTIME	Device has broken DFU runtime support

enum DfuDeviceAttributes

The device DFU attributes.

Members

DFU_DEVICE_ATTRIBUTE_NONE	No attributes set
DFU_DEVICE_ATTRIBUTE_CAN_DOWNLOAD	Can download from host->device
DFU_DEVICE_ATTRIBUTE_CAN_UPLOAD	Can upload from device->host
DFU_DEVICE_ATTRIBUTE_MANIFEST_TOL	Can answer GetStatus in manifest
DFU_DEVICE_ATTRIBUTE_WILL_DETACH	Will self-detach
DFU_DEVICE_ATTRIBUTE_CAN_ACCELERATE	Use a larger transfer size for speed

struct DfuDeviceClass

struct DfuDeviceClass {
	GObjectClass		 parent_class;
	void			(*status_changed) (DfuDevice *device,
							 DfuStatus	 status);
	void			(*state_changed) (DfuDevice *device,
							 DfuState	 state);
	void			(*percentage_changed) (DfuDevice *device,
							 guint		 percentage);
	void			(*action_changed) (DfuDevice *device,
							 DfuAction	 action);
};

DfuDevice

typedef struct _DfuDevice DfuDevice;