FuDevice

FuDevice — a physical or logical device

Synopsis

#define             FU_TYPE_DEVICE
struct              FuDeviceClass;
#define             FU_DEVICE_REMOVE_DELAY_RE_ENUMERATE
#define             FU_DEVICE_REMOVE_DELAY_USER_REPLUG
FuDevice *          fu_device_new                       (void);
#define             fu_device_add_flag                  (d,
                                                         v)
#define             fu_device_remove_flag               (d,
                                                         v)
#define             fu_device_has_flag                  (d,
                                                         v)
#define             fu_device_add_checksum              (d,
                                                         v)
#define             fu_device_add_icon                  (d,
                                                         v)
#define             fu_device_set_created               (d,
                                                         v)
#define             fu_device_set_description           (d,
                                                         v)
#define             fu_device_set_flags                 (d,
                                                         v)
#define             fu_device_has_guid                  (d,
                                                         v)
#define             fu_device_set_modified              (d,
                                                         v)
#define             fu_device_set_plugin                (d,
                                                         v)
#define             fu_device_set_summary               (d,
                                                         v)
#define             fu_device_set_update_error          (d,
                                                         v)
#define             fu_device_set_update_state          (d,
                                                         v)
#define             fu_device_set_vendor                (d,
                                                         v)
#define             fu_device_set_vendor_id             (d,
                                                         v)
#define             fu_device_set_version               (d,
                                                         v)
#define             fu_device_set_version_lowest        (d,
                                                         v)
#define             fu_device_set_version_bootloader    (d,
                                                         v)
#define             fu_device_set_flashes_left          (d,
                                                         v)
#define             fu_device_get_checksums             (d)
#define             fu_device_get_flags                 (d)
#define             fu_device_get_created               (d)
#define             fu_device_get_modified              (d)
#define             fu_device_get_guids                 (d)
#define             fu_device_get_guid_default          (d)
#define             fu_device_get_icons                 (d)
#define             fu_device_get_name                  (d)
#define             fu_device_get_id                    (d)
#define             fu_device_get_plugin                (d)
#define             fu_device_get_update_error          (d)
#define             fu_device_get_update_state          (d)
#define             fu_device_get_vendor                (d)
#define             fu_device_get_version               (d)
#define             fu_device_get_version_lowest        (d)
#define             fu_device_get_version_bootloader    (d)
#define             fu_device_get_vendor_id             (d)
#define             fu_device_get_flashes_left          (d)
gchar *             fu_device_to_string                 (FuDevice *device);
const gchar *       fu_device_get_equivalent_id         (FuDevice *device);
void                fu_device_set_equivalent_id         (FuDevice *device,
                                                         const gchar *equivalent_id);
void                fu_device_add_guid                  (FuDevice *device,
                                                         const gchar *guid);
gchar *             fu_device_get_guids_as_str          (FuDevice *device);
FuDevice *          fu_device_get_alternate             (FuDevice *device);
void                fu_device_set_alternate             (FuDevice *device,
                                                         FuDevice *alternate);
FuDevice *          fu_device_get_parent                (FuDevice *device);
GPtrArray *         fu_device_get_children              (FuDevice *device);
void                fu_device_add_child                 (FuDevice *device,
                                                         FuDevice *child);
void                fu_device_add_parent_guid           (FuDevice *device,
                                                         const gchar *guid);
const gchar *       fu_device_get_metadata              (FuDevice *device,
                                                         const gchar *key);
gboolean            fu_device_get_metadata_boolean      (FuDevice *device,
                                                         const gchar *key);
guint               fu_device_get_metadata_integer      (FuDevice *device,
                                                         const gchar *key);
void                fu_device_set_metadata              (FuDevice *device,
                                                         const gchar *key,
                                                         const gchar *value);
void                fu_device_set_metadata_boolean      (FuDevice *device,
                                                         const gchar *key,
                                                         gboolean value);
void                fu_device_set_metadata_integer      (FuDevice *device,
                                                         const gchar *key,
                                                         guint value);
void                fu_device_set_id                    (FuDevice *device,
                                                         const gchar *id);
const gchar *       fu_device_get_platform_id           (FuDevice *device);
void                fu_device_set_platform_id           (FuDevice *device,
                                                         const gchar *platform_id);
const gchar *       fu_device_get_serial                (FuDevice *device);
void                fu_device_set_serial                (FuDevice *device,
                                                         const gchar *serial);
const gchar *       fu_device_get_plugin_hints          (FuDevice *device);
void                fu_device_set_plugin_hints          (FuDevice *device,
                                                         const gchar *plugin_hints);
void                fu_device_set_name                  (FuDevice *device,
                                                         const gchar *value);
guint               fu_device_get_remove_delay          (FuDevice *device);
void                fu_device_set_remove_delay          (FuDevice *device,
                                                         guint remove_delay);
FwupdStatus         fu_device_get_status                (FuDevice *device);
void                fu_device_set_status                (FuDevice *device,
                                                         FwupdStatus status);
guint               fu_device_get_progress              (FuDevice *device);
void                fu_device_set_progress              (FuDevice *device,
                                                         guint progress);
void                fu_device_set_progress_full         (FuDevice *device,
                                                         gsize progress_done,
                                                         gsize progress_total);
void                fu_device_set_quirks                (FuDevice *device,
                                                         FuQuirks *quirks);
FuQuirks *          fu_device_get_quirks                (FuDevice *device);
FwupdRelease *      fu_device_get_release_default       (FuDevice *device);
gboolean            fu_device_write_firmware            (FuDevice *device,
                                                         GBytes *fw,
                                                         GError **error);
GBytes *            fu_device_read_firmware             (FuDevice *device,
                                                         GError **error);
gboolean            fu_device_attach                    (FuDevice *device,
                                                         GError **error);
gboolean            fu_device_detach                    (FuDevice *device,
                                                         GError **error);

Description

An object that represents a physical or logical device.

See also: FuDeviceLocker

Details

FU_TYPE_DEVICE

#define FU_TYPE_DEVICE (fu_device_get_type ())

struct FuDeviceClass

struct FuDeviceClass {
	FwupdDeviceClass	 parent_class;
	void			 (*to_string)		(FuDevice *device,
							 GString *str);
	gboolean		 (*write_firmware) (FuDevice *device,
							 GBytes		*fw,
							 GError		**error);
	GBytes			*(*read_firmware) (FuDevice *device,
							 GError		**error);
	gboolean		 (*detach)		(FuDevice *device,
							 GError		**error);
	gboolean		 (*attach)		(FuDevice *device,
							 GError		**error);
};

FU_DEVICE_REMOVE_DELAY_RE_ENUMERATE

#define FU_DEVICE_REMOVE_DELAY_RE_ENUMERATE		5000

The default removal delay for device re-enumeration taking into account a chain of slow USB hubs. This should be used when the device is able to reset itself between bootloader->runtime->bootloader.


FU_DEVICE_REMOVE_DELAY_USER_REPLUG

#define FU_DEVICE_REMOVE_DELAY_USER_REPLUG		20000

The default removal delay for device re-plug taking into account humans being slow and clumsy. This should be used when the user has to do something, e.g. unplug, press a magic button and then replug.


fu_device_new ()

FuDevice *          fu_device_new                       (void);

fu_device_add_flag()

#define fu_device_add_flag(d,v)			fwupd_device_add_flag(FWUPD_DEVICE(d),v)

fu_device_remove_flag()

#define fu_device_remove_flag(d,v)		fwupd_device_remove_flag(FWUPD_DEVICE(d),v)

fu_device_has_flag()

#define fu_device_has_flag(d,v)			fwupd_device_has_flag(FWUPD_DEVICE(d),v)

fu_device_add_checksum()

#define fu_device_add_checksum(d,v)		fwupd_device_add_checksum(FWUPD_DEVICE(d),v)

fu_device_add_icon()

#define fu_device_add_icon(d,v)			fwupd_device_add_icon(FWUPD_DEVICE(d),v)

fu_device_set_created()

#define fu_device_set_created(d,v)		fwupd_device_set_created(FWUPD_DEVICE(d),v)

fu_device_set_description()

#define fu_device_set_description(d,v)		fwupd_device_set_description(FWUPD_DEVICE(d),v)

fu_device_set_flags()

#define fu_device_set_flags(d,v)		fwupd_device_set_flags(FWUPD_DEVICE(d),v)

fu_device_has_guid()

#define fu_device_has_guid(d,v)			fwupd_device_has_guid(FWUPD_DEVICE(d),v)

fu_device_set_modified()

#define fu_device_set_modified(d,v)		fwupd_device_set_modified(FWUPD_DEVICE(d),v)

fu_device_set_plugin()

#define fu_device_set_plugin(d,v)		fwupd_device_set_plugin(FWUPD_DEVICE(d),v)

fu_device_set_summary()

#define fu_device_set_summary(d,v)		fwupd_device_set_summary(FWUPD_DEVICE(d),v)

fu_device_set_update_error()

#define fu_device_set_update_error(d,v)		fwupd_device_set_update_error(FWUPD_DEVICE(d),v)

fu_device_set_update_state()

#define fu_device_set_update_state(d,v)		fwupd_device_set_update_state(FWUPD_DEVICE(d),v)

fu_device_set_vendor()

#define fu_device_set_vendor(d,v)		fwupd_device_set_vendor(FWUPD_DEVICE(d),v)

fu_device_set_vendor_id()

#define fu_device_set_vendor_id(d,v)		fwupd_device_set_vendor_id(FWUPD_DEVICE(d),v)

fu_device_set_version()

#define fu_device_set_version(d,v)		fwupd_device_set_version(FWUPD_DEVICE(d),v)

fu_device_set_version_lowest()

#define fu_device_set_version_lowest(d,v) fwupd_device_set_version_lowest(FWUPD_DEVICE(d),v)

fu_device_set_version_bootloader()

#define fu_device_set_version_bootloader(d,v) fwupd_device_set_version_bootloader(FWUPD_DEVICE(d),v)

fu_device_set_flashes_left()

#define fu_device_set_flashes_left(d,v)		fwupd_device_set_flashes_left(FWUPD_DEVICE(d),v)

fu_device_get_checksums()

#define fu_device_get_checksums(d)		fwupd_device_get_checksums(FWUPD_DEVICE(d))

fu_device_get_flags()

#define fu_device_get_flags(d)			fwupd_device_get_flags(FWUPD_DEVICE(d))

fu_device_get_created()

#define fu_device_get_created(d)		fwupd_device_get_created(FWUPD_DEVICE(d))

fu_device_get_modified()

#define fu_device_get_modified(d)		fwupd_device_get_modified(FWUPD_DEVICE(d))

fu_device_get_guids()

#define fu_device_get_guids(d)			fwupd_device_get_guids(FWUPD_DEVICE(d))

fu_device_get_guid_default()

#define fu_device_get_guid_default(d)		fwupd_device_get_guid_default(FWUPD_DEVICE(d))

fu_device_get_icons()

#define fu_device_get_icons(d)			fwupd_device_get_icons(FWUPD_DEVICE(d))

fu_device_get_name()

#define fu_device_get_name(d)			fwupd_device_get_name(FWUPD_DEVICE(d))

fu_device_get_id()

#define fu_device_get_id(d)			fwupd_device_get_id(FWUPD_DEVICE(d))

fu_device_get_plugin()

#define fu_device_get_plugin(d)			fwupd_device_get_plugin(FWUPD_DEVICE(d))

fu_device_get_update_error()

#define fu_device_get_update_error(d)		fwupd_device_get_update_error(FWUPD_DEVICE(d))

fu_device_get_update_state()

#define fu_device_get_update_state(d)		fwupd_device_get_update_state(FWUPD_DEVICE(d))

fu_device_get_vendor()

#define fu_device_get_vendor(d)			fwupd_device_get_vendor(FWUPD_DEVICE(d))

fu_device_get_version()

#define fu_device_get_version(d)		fwupd_device_get_version(FWUPD_DEVICE(d))

fu_device_get_version_lowest()

#define fu_device_get_version_lowest(d)		fwupd_device_get_version_lowest(FWUPD_DEVICE(d))

fu_device_get_version_bootloader()

#define fu_device_get_version_bootloader(d) fwupd_device_get_version_bootloader(FWUPD_DEVICE(d))

fu_device_get_vendor_id()

#define fu_device_get_vendor_id(d)		fwupd_device_get_vendor_id(FWUPD_DEVICE(d))

fu_device_get_flashes_left()

#define fu_device_get_flashes_left(d)		fwupd_device_get_flashes_left(FWUPD_DEVICE(d))

fu_device_to_string ()

gchar *             fu_device_to_string                 (FuDevice *device);

This allows us to easily print the FwupdDevice, the FwupdRelease and the daemon-specific metadata.

device :

A FuDevice

Returns :

a string value, or NULL for invalid.

Since 0.9.8


fu_device_get_equivalent_id ()

const gchar *       fu_device_get_equivalent_id         (FuDevice *device);

fu_device_set_equivalent_id ()

void                fu_device_set_equivalent_id         (FuDevice *device,
                                                         const gchar *equivalent_id);

fu_device_add_guid ()

void                fu_device_add_guid                  (FuDevice *device,
                                                         const gchar *guid);

Adds a GUID to the device. If the guid argument is not a valid GUID then it is converted to a GUID using as_utils_guid_from_string().

device :

A FuDevice

guid :

A GUID, e.g. `2082b5e0-7a64-478a-b1b2-e3404fab6dad`

Since 0.7.2


fu_device_get_guids_as_str ()

gchar *             fu_device_get_guids_as_str          (FuDevice *device);

Gets the device GUIDs as a joined string, which may be useful for error messages.

device :

A FuDevice

Returns :

a string, which may be empty length but not NULL

Since 1.0.8


fu_device_get_alternate ()

FuDevice *          fu_device_get_alternate             (FuDevice *device);

Gets any alternate device. An alternate device may be linked to the primary device in some way.

device :

A FuDevice

Returns :

a FuDevice or NULL. [transfer none]

Since 0.7.2


fu_device_set_alternate ()

void                fu_device_set_alternate             (FuDevice *device,
                                                         FuDevice *alternate);

Sets any alternate device. An alternate device may be linked to the primary device in some way.

device :

A FuDevice

alternate :

Another FuDevice

Since 0.7.2


fu_device_get_parent ()

FuDevice *          fu_device_get_parent                (FuDevice *device);

Gets any parent device. An parent device is logically "above" the current device and this may be reflected in client tools.

This information also allows the plugin to optionally verify the parent device, for instance checking the parent device firmware version.

The parent object is not refcounted and if destroyed this function will then return NULL.

device :

A FuDevice

Returns :

a FuDevice or NULL. [transfer none]

Since 1.0.8


fu_device_get_children ()

GPtrArray *         fu_device_get_children              (FuDevice *device);

Gets any child devices. A child device is logically "below" the current device and this may be reflected in client tools.

device :

A FuDevice

Returns :

child devices. [transfer none][element-type FuDevice]

Since 1.0.8


fu_device_add_child ()

void                fu_device_add_child                 (FuDevice *device,
                                                         FuDevice *child);

Sets any child device. An child device is logically linked to the primary device in some way.

device :

A FuDevice

child :

Another FuDevice

Since 1.0.8


fu_device_add_parent_guid ()

void                fu_device_add_parent_guid           (FuDevice *device,
                                                         const gchar *guid);

Sets any parent device using a GUID. An parent device is logically linked to the primary device in some way and can be added before or after device.

The GUIDs are searched in order, and so the order of adding GUIDs may be important if more than one parent device might match.

device :

A FuDevice

guid :

a GUID

Since 1.0.8


fu_device_get_metadata ()

const gchar *       fu_device_get_metadata              (FuDevice *device,
                                                         const gchar *key);

Gets an item of metadata from the device.

device :

A FuDevice

key :

the key

Returns :

a string value, or NULL for unfound.

Since 0.1.0


fu_device_get_metadata_boolean ()

gboolean            fu_device_get_metadata_boolean      (FuDevice *device,
                                                         const gchar *key);

Gets an item of metadata from the device.

device :

A FuDevice

key :

the key

Returns :

a boolean value, or FALSE for unfound or failure to parse.

Since 0.9.7


fu_device_get_metadata_integer ()

guint               fu_device_get_metadata_integer      (FuDevice *device,
                                                         const gchar *key);

Gets an item of metadata from the device.

device :

A FuDevice

key :

the key

Returns :

a string value, or G_MAXUINT for unfound or failure to parse.

Since 0.9.7


fu_device_set_metadata ()

void                fu_device_set_metadata              (FuDevice *device,
                                                         const gchar *key,
                                                         const gchar *value);

Sets an item of metadata on the device.

device :

A FuDevice

key :

the key

value :

the string value

Since 0.1.0


fu_device_set_metadata_boolean ()

void                fu_device_set_metadata_boolean      (FuDevice *device,
                                                         const gchar *key,
                                                         gboolean value);

Sets an item of metadata on the device. When value is set to TRUE the actual stored value is "true".

device :

A FuDevice

key :

the key

value :

the boolean value

Since 0.9.7


fu_device_set_metadata_integer ()

void                fu_device_set_metadata_integer      (FuDevice *device,
                                                         const gchar *key,
                                                         guint value);

Sets an item of metadata on the device. The integer is stored as a base-10 string internally.

device :

A FuDevice

key :

the key

value :

the unsigned integer value

Since 0.9.7


fu_device_set_id ()

void                fu_device_set_id                    (FuDevice *device,
                                                         const gchar *id);

Sets the ID on the device. The ID should represent the *connection* of the device, so that any similar device plugged into a different slot will have a different id string.

The id will be converted to a SHA1 hash before the device is added to the daemon, and plugins should not assume that the ID that is set here is the same as what is returned by fu_device_get_id().

device :

A FuDevice

id :

a string, e.g. `tbt-port1`

Since 0.7.1


fu_device_get_platform_id ()

const gchar *       fu_device_get_platform_id           (FuDevice *device);

Gets the Platform ID set for the device, which represents the connection string used to compare devices.

device :

A FuDevice

Returns :

a string value, or NULL if never set.

Since 1.0.2


fu_device_set_platform_id ()

void                fu_device_set_platform_id           (FuDevice *device,
                                                         const gchar *platform_id);

Sets the Platform ID on the device. If unset, the ID will automatically be set using a hash of the platform_id value.

device :

A FuDevice

platform_id :

a platform string, e.g. `/sys/devices/usb1/1-1/1-1.2`

Since 1.0.2


fu_device_get_serial ()

const gchar *       fu_device_get_serial                (FuDevice *device);

Gets the serial number for the device.

device :

A FuDevice

Returns :

a string value, or NULL if never set.

Since 1.0.3


fu_device_set_serial ()

void                fu_device_set_serial                (FuDevice *device,
                                                         const gchar *serial);

Sets the serial number for the device.

device :

A FuDevice

serial :

a serial number string, e.g. `0000123`

Since 1.0.3


fu_device_get_plugin_hints ()

const gchar *       fu_device_get_plugin_hints          (FuDevice *device);

Gets the plugin hint for the device from the quirk system.

device :

A FuDevice

Returns :

a string value, or NULL if never set.

Since 1.0.3


fu_device_set_plugin_hints ()

void                fu_device_set_plugin_hints          (FuDevice *device,
                                                         const gchar *plugin_hints);

Sets the hint the the plugin from the quirk system that can be used to do affect device matching. The actual string format is defined by the plugin.

device :

A FuDevice

plugin_hints :

a string

Since 1.0.3


fu_device_set_name ()

void                fu_device_set_name                  (FuDevice *device,
                                                         const gchar *value);

Sets the name on the device. Any invalid parts will be converted or removed.

device :

A FuDevice

value :

a device name

Since 0.7.1


fu_device_get_remove_delay ()

guint               fu_device_get_remove_delay          (FuDevice *device);

Returns the maximum delay expected when replugging the device going into bootloader mode.

device :

A FuDevice

Returns :

time in milliseconds

Since 1.0.2


fu_device_set_remove_delay ()

void                fu_device_set_remove_delay          (FuDevice *device,
                                                         guint remove_delay);

Sets the amount of time a device is allowed to return in bootloader mode.

NOTE: this should be less than 3000ms for devices that just have to reset and automatically re-enumerate, but significantly longer if it involves a user removing a cable, pressing several buttons and removing a cable. A suggested value for this would be 10,000ms.

device :

A FuDevice

remove_delay :

the remove_delay value

Since 1.0.2


fu_device_get_status ()

FwupdStatus         fu_device_get_status                (FuDevice *device);

Returns what the device is currently doing.

device :

A FuDevice

Returns :

the status value, e.g. FWUPD_STATUS_DEVICE_WRITE

Since 1.0.3


fu_device_set_status ()

void                fu_device_set_status                (FuDevice *device,
                                                         FwupdStatus status);

Sets what the device is currently doing.

device :

A FuDevice

status :

the status value, e.g. FWUPD_STATUS_DEVICE_WRITE

Since 1.0.3


fu_device_get_progress ()

guint               fu_device_get_progress              (FuDevice *device);

Returns the progress completion.

device :

A FuDevice

Returns :

value in percent

Since 1.0.3


fu_device_set_progress ()

void                fu_device_set_progress              (FuDevice *device,
                                                         guint progress);

Sets the progress completion.

device :

A FuDevice

progress :

the progress percentage value

Since 1.0.3


fu_device_set_progress_full ()

void                fu_device_set_progress_full         (FuDevice *device,
                                                         gsize progress_done,
                                                         gsize progress_total);

Sets the progress completion using the raw progress values.

device :

A FuDevice

progress_done :

the bytes already done

progress_total :

the total number of bytes

Since 1.0.3


fu_device_set_quirks ()

void                fu_device_set_quirks                (FuDevice *device,
                                                         FuQuirks *quirks);

Sets the optional quirk information which may be useful to this device. This is typically set after the FuDevice has been created, but before the device has been opened or probed.

device :

A FuDevice

quirks :

A FuQuirks, or NULL

Since 1.0.3


fu_device_get_quirks ()

FuQuirks *          fu_device_get_quirks                (FuDevice *device);

Gets the quirk information which may be useful to this device.

device :

A FuDevice

Returns :

the FuQuirks object, or NULL. [transfer none]

Since 1.0.3


fu_device_get_release_default ()

FwupdRelease *      fu_device_get_release_default       (FuDevice *device);

Gets the default release for the device, creating one if not found.

device :

A FuDevice

Returns :

the FwupdRelease object. [transfer none]

Since 1.0.5


fu_device_write_firmware ()

gboolean            fu_device_write_firmware            (FuDevice *device,
                                                         GBytes *fw,
                                                         GError **error);

Writes firmware to the device by calling a plugin-specific vfunc.

device :

A FuDevice

fw :

A GBytes

error :

A GError

Returns :

TRUE on success

Since 1.0.8


fu_device_read_firmware ()

GBytes *            fu_device_read_firmware             (FuDevice *device,
                                                         GError **error);

Reads firmware from the device by calling a plugin-specific vfunc.

device :

A FuDevice

error :

A GError

Returns :

A GBytes, or NULL for error. [transfer full]

Since 1.0.8


fu_device_attach ()

gboolean            fu_device_attach                    (FuDevice *device,
                                                         GError **error);

Attaches a device from the bootloader into application mode.

device :

A FuDevice

error :

A GError

Returns :

TRUE on success

Since 1.0.8


fu_device_detach ()

gboolean            fu_device_detach                    (FuDevice *device,
                                                         GError **error);

Detaches a device from the application into bootloader mode.

device :

A FuDevice

error :

A GError

Returns :

TRUE on success

Since 1.0.8