DfuDevice

DfuDevice — Object representing a DFU-capable device

Functions

Types and Values

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.

See also: DfuTarget, DfuFirmware

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

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;