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

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

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;