FuPlugin

FuPlugin — a daemon plugin

Synopsis

#define             FU_TYPE_PLUGIN
struct              FuPluginClass;
enum                FuPluginVerifyFlags;
enum                FuPluginRule;
typedef             FuPluginData;
const gchar *       fu_plugin_get_name                  (FuPlugin *plugin);
FuPluginData *      fu_plugin_get_data                  (FuPlugin *plugin);
FuPluginData *      fu_plugin_alloc_data                (FuPlugin *plugin,
                                                         gsize data_sz);
gboolean            fu_plugin_get_enabled               (FuPlugin *plugin);
void                fu_plugin_set_enabled               (FuPlugin *plugin,
                                                         gboolean enabled);
GUsbContext *       fu_plugin_get_usb_context           (FuPlugin *plugin);
GPtrArray *         fu_plugin_get_supported             (FuPlugin *plugin);
void                fu_plugin_device_add                (FuPlugin *plugin,
                                                         FuDevice *device);
void                fu_plugin_device_add_delay          (FuPlugin *plugin,
                                                         FuDevice *device);
void                fu_plugin_device_remove             (FuPlugin *plugin,
                                                         FuDevice *device);
void                fu_plugin_device_register           (FuPlugin *plugin,
                                                         FuDevice *device);
void                fu_plugin_set_status                (FuPlugin *plugin,
                                                         FwupdStatus status);
void                fu_plugin_set_percentage            (FuPlugin *plugin,
                                                         guint percentage);
void                fu_plugin_request_recoldplug        (FuPlugin *plugin);
void                fu_plugin_set_coldplug_delay        (FuPlugin *plugin,
                                                         guint duration);
gpointer            fu_plugin_cache_lookup              (FuPlugin *plugin,
                                                         const gchar *id);
void                fu_plugin_cache_remove              (FuPlugin *plugin,
                                                         const gchar *id);
void                fu_plugin_cache_add                 (FuPlugin *plugin,
                                                         const gchar *id,
                                                         gpointer dev);
gboolean            fu_plugin_check_hwid                (FuPlugin *plugin,
                                                         const gchar *hwid);
gboolean            fu_plugin_check_supported           (FuPlugin *plugin,
                                                         const gchar *guid);
const gchar *       fu_plugin_get_dmi_value             (FuPlugin *plugin,
                                                         const gchar *dmi_id);
const gchar *       fu_plugin_get_smbios_string         (FuPlugin *plugin,
                                                         guint8 structure_type,
                                                         guint8 offset);
GBytes *            fu_plugin_get_smbios_data           (FuPlugin *plugin,
                                                         guint8 structure_type);
void                fu_plugin_add_rule                  (FuPlugin *plugin,
                                                         FuPluginRule rule,
                                                         const gchar *name);
FuQuirks *          fu_plugin_get_quirks                (FuPlugin *plugin);
const gchar *       fu_plugin_lookup_quirk_by_id        (FuPlugin *plugin,
                                                         const gchar *prefix,
                                                         const gchar *id);
const gchar *       fu_plugin_lookup_quirk_by_usb_device
                                                        (FuPlugin *plugin,
                                                         const gchar *prefix,
                                                         GUsbDevice *dev);
void                fu_plugin_add_report_metadata       (FuPlugin *plugin,
                                                         const gchar *key,
                                                         const gchar *value);
gchar *             fu_plugin_get_config_value          (FuPlugin *plugin,
                                                         const gchar *key);
void                fu_plugin_add_runtime_version       (FuPlugin *plugin,
                                                         const gchar *component_id,
                                                         const gchar *version);
void                fu_plugin_add_compile_version       (FuPlugin *plugin,
                                                         const gchar *component_id,
                                                         const gchar *version);

Description

An object that represents a plugin run by the daemon.

See also: FuDevice

Details

FU_TYPE_PLUGIN

#define FU_TYPE_PLUGIN (fu_plugin_get_type ())

struct FuPluginClass

struct FuPluginClass {
	GObjectClass	 parent_class;
	/* signals */
	void		 (* device_added)		(FuPlugin *plugin,
							 FuDevice *device);
	void		 (* device_removed)		(FuPlugin *plugin,
							 FuDevice *device);
	void		 (* status_changed)		(FuPlugin *plugin,
							 FwupdStatus	 status);
	void		 (* percentage_changed)		(FuPlugin *plugin,
							 guint		 percentage);
	void		 (* recoldplug)			(FuPlugin *plugin);
	void		 (* set_coldplug_delay)		(FuPlugin *plugin,
							 guint		 duration);
	void		 (* device_register)		(FuPlugin *plugin,
							 FuDevice *device);
};

enum FuPluginVerifyFlags

typedef enum {
	FU_PLUGIN_VERIFY_FLAG_NONE		= 0,
} FuPluginVerifyFlags;

Flags used when verifying, currently unused.

FU_PLUGIN_VERIFY_FLAG_NONE

No flags set

enum FuPluginRule

typedef enum {
	FU_PLUGIN_RULE_CONFLICTS,
	FU_PLUGIN_RULE_RUN_AFTER,
	FU_PLUGIN_RULE_RUN_BEFORE,
} FuPluginRule;

The rules used for ordering plugins. Plugins are expected to add rules in fu_plugin_initialize().

FU_PLUGIN_RULE_CONFLICTS

The plugin conflicts with another

FU_PLUGIN_RULE_RUN_AFTER

Order the plugin after another

FU_PLUGIN_RULE_RUN_BEFORE

Order the plugin before another

FuPluginData

typedef struct FuPluginData FuPluginData;

fu_plugin_get_name ()

const gchar *       fu_plugin_get_name                  (FuPlugin *plugin);

Gets the plugin name.

plugin :

A FuPlugin

Returns :

a plugin name, or NULL for unknown.

Since 0.8.0


fu_plugin_get_data ()

FuPluginData *      fu_plugin_get_data                  (FuPlugin *plugin);

Gets the per-plugin allocated private data. This will return NULL unless fu_plugin_alloc_data() has been called by the plugin.

plugin :

A FuPlugin

Returns :

a pointer to a structure, or NULL for unset. [transfer none]

Since 0.8.0


fu_plugin_alloc_data ()

FuPluginData *      fu_plugin_alloc_data                (FuPlugin *plugin,
                                                         gsize data_sz);

Allocates the per-plugin allocated private data.

plugin :

A FuPlugin

data_sz :

the size to allocate

Returns :

a pointer to a structure, or NULL for unset. [transfer full]

Since 0.8.0


fu_plugin_get_enabled ()

gboolean            fu_plugin_get_enabled               (FuPlugin *plugin);

Returns if the plugin is enabled. Plugins may self-disable using fu_plugin_set_enabled() or can be disabled by the daemon.

plugin :

A FuPlugin

Returns :

TRUE if the plugin is currently enabled.

Since 0.8.0


fu_plugin_set_enabled ()

void                fu_plugin_set_enabled               (FuPlugin *plugin,
                                                         gboolean enabled);

Enables or disables a plugin. Plugins can self-disable at any point.

plugin :

A FuPlugin

enabled :

the enabled value

Since 0.8.0


fu_plugin_get_usb_context ()

GUsbContext *       fu_plugin_get_usb_context           (FuPlugin *plugin);

Gets the shared USB context that all plugins can use.

plugin :

A FuPlugin

Returns :

a GUsbContext. [transfer none]

Since 0.8.0


fu_plugin_get_supported ()

GPtrArray *         fu_plugin_get_supported             (FuPlugin *plugin);

Gets all the device GUIDs supported by the daemon.

plugin :

A FuPlugin

Returns :

GUIDs. [element-type utf8][transfer none]

Since 1.0.0


fu_plugin_device_add ()

void                fu_plugin_device_add                (FuPlugin *plugin,
                                                         FuDevice *device);

Asks the daemon to add a device to the exported list. If this device ID has already been added by a different plugin then this request will be ignored.

Plugins should use fu_plugin_device_add_delay() if they are not capable of actually flashing an image to the hardware so that higher-priority plugins can add the device themselves.

plugin :

A FuPlugin

device :

A FuDevice

Since 0.8.0


fu_plugin_device_add_delay ()

void                fu_plugin_device_add_delay          (FuPlugin *plugin,
                                                         FuDevice *device);

Asks the daemon to add a device to the exported list after a small delay.

plugin :

A FuPlugin

device :

A FuDevice

Since 0.8.0


fu_plugin_device_remove ()

void                fu_plugin_device_remove             (FuPlugin *plugin,
                                                         FuDevice *device);

Asks the daemon to remove a device from the exported list.

plugin :

A FuPlugin

device :

A FuDevice

Since 0.8.0


fu_plugin_device_register ()

void                fu_plugin_device_register           (FuPlugin *plugin,
                                                         FuDevice *device);

Registers the device with other plugins so they can set metadata.

Plugins do not have to call this manually as this is done automatically when using fu_plugin_device_add(). They may wish to use this manually if for intance the coldplug should be ignored based on the metadata set from other plugins.

plugin :

A FuPlugin

device :

A FuDevice

Since 0.9.7


fu_plugin_set_status ()

void                fu_plugin_set_status                (FuPlugin *plugin,
                                                         FwupdStatus status);

fu_plugin_set_percentage ()

void                fu_plugin_set_percentage            (FuPlugin *plugin,
                                                         guint percentage);

fu_plugin_request_recoldplug ()

void                fu_plugin_request_recoldplug        (FuPlugin *plugin);

Ask all the plugins to coldplug all devices, which will include the prepare() and cleanup() phases. Duplicate devices added will be ignored.

plugin :

A FuPlugin

Since 0.8.0


fu_plugin_set_coldplug_delay ()

void                fu_plugin_set_coldplug_delay        (FuPlugin *plugin,
                                                         guint duration);

Set the minimum time that should be waited inbetween the call to fu_plugin_coldplug_prepare() and fu_plugin_coldplug(). This is usually going to be the minimum hardware initialisation time from a datasheet.

It is better to use this function rather than using a sleep() in the plugin itself as then only one delay is done in the daemon rather than waiting for each coldplug prepare in a serial way.

Additionally, very long delays should be avoided as the daemon will be blocked from processing requests whilst the coldplug delay is being performed.

plugin :

A FuPlugin

duration :

A delay in milliseconds

Since 0.8.0


fu_plugin_cache_lookup ()

gpointer            fu_plugin_cache_lookup              (FuPlugin *plugin,
                                                         const gchar *id);

Finds an object in the per-plugin cache.

plugin :

A FuPlugin

id :

the key

Returns :

a GObject, or NULL for unfound. [transfer none]

Since 0.8.0


fu_plugin_cache_remove ()

void                fu_plugin_cache_remove              (FuPlugin *plugin,
                                                         const gchar *id);

Removes an object from the per-plugin cache.

plugin :

A FuPlugin

id :

the key

Since 0.8.0


fu_plugin_cache_add ()

void                fu_plugin_cache_add                 (FuPlugin *plugin,
                                                         const gchar *id,
                                                         gpointer dev);

Adds an object to the per-plugin cache.

plugin :

A FuPlugin

id :

the key

dev :

a GObject, typically a FuDevice

Since 0.8.0


fu_plugin_check_hwid ()

gboolean            fu_plugin_check_hwid                (FuPlugin *plugin,
                                                         const gchar *hwid);

Checks to see if a specific GUID exists. All hardware IDs on a specific system can be shown using the `fwupdmgr hwids` command.

plugin :

A FuPlugin

hwid :

A Hardware ID GUID, e.g. `6de5d951-d755-576b-bd09-c5cf66b27234`

Returns :

TRUE if the HwId is found on the system.

Since 0.9.1


fu_plugin_check_supported ()

gboolean            fu_plugin_check_supported           (FuPlugin *plugin,
                                                         const gchar *guid);

Checks to see if a specific device GUID is supported, i.e. available in the AppStream metadata.

plugin :

A FuPlugin

guid :

A Hardware ID GUID, e.g. `6de5d951-d755-576b-bd09-c5cf66b27234`

Returns :

TRUE if the device is supported.

Since 1.0.0


fu_plugin_get_dmi_value ()

const gchar *       fu_plugin_get_dmi_value             (FuPlugin *plugin,
                                                         const gchar *dmi_id);

Gets a hardware DMI value.

plugin :

A FuPlugin

dmi_id :

A DMI ID, e.g. `BiosVersion`

Returns :

The string, or NULL

Since 0.9.7


fu_plugin_get_smbios_string ()

const gchar *       fu_plugin_get_smbios_string         (FuPlugin *plugin,
                                                         guint8 structure_type,
                                                         guint8 offset);

Gets a hardware SMBIOS string.

The type and offset can be referenced from the DMTF SMBIOS specification: https://www.dmtf.org/sites/default/files/standards/documents/DSP0134_3.1.1.pdf

plugin :

A FuPlugin

structure_type :

A SMBIOS structure type, e.g. FU_SMBIOS_STRUCTURE_TYPE_BIOS

offset :

A SMBIOS offset

Returns :

A string, or NULL

Since 0.9.8


fu_plugin_get_smbios_data ()

GBytes *            fu_plugin_get_smbios_data           (FuPlugin *plugin,
                                                         guint8 structure_type);

Gets a hardware SMBIOS data.

plugin :

A FuPlugin

structure_type :

A SMBIOS structure type, e.g. FU_SMBIOS_STRUCTURE_TYPE_BIOS

Returns :

A GBytes, or NULL. [transfer none]

Since 0.9.8


fu_plugin_add_rule ()

void                fu_plugin_add_rule                  (FuPlugin *plugin,
                                                         FuPluginRule rule,
                                                         const gchar *name);

If the plugin name is found, the rule will be used to sort the plugin list, for example the plugin specified by name will be ordered after this plugin when FU_PLUGIN_RULE_RUN_AFTER is used.

NOTE: The depsolver is iterative and may not solve overly-complicated rules; If depsolving fails then fwupd will not start.

plugin :

a FuPlugin

rule :

a FuPluginRule, e.g. FU_PLUGIN_RULE_CONFLICTS

name :

a plugin name, e.g. `upower`

fu_plugin_get_quirks ()

FuQuirks *          fu_plugin_get_quirks                (FuPlugin *plugin);

Returns the hardware database object. This can be used to discover device quirks or other device-specific settings.

plugin :

A FuPlugin

Returns :

a FuQuirks, or NULL if not set. [transfer none]

Since 1.0.1


fu_plugin_lookup_quirk_by_id ()

const gchar *       fu_plugin_lookup_quirk_by_id        (FuPlugin *plugin,
                                                         const gchar *prefix,
                                                         const gchar *id);

Looks up an entry in the hardware database using a string value.

plugin :

A FuPlugin

prefix :

A string prefix that matches the quirks file basename, e.g. "dfu-quirks"

id :

An ID to match the entry, e.g. "012345"

Returns :

values from the database, or NULL if not found. [transfer none]

Since 1.0.1


fu_plugin_lookup_quirk_by_usb_device ()

const gchar *       fu_plugin_lookup_quirk_by_usb_device
                                                        (FuPlugin *plugin,
                                                         const gchar *prefix,
                                                         GUsbDevice *dev);

Looks up an entry in the hardware database using various keys generated from dev.

plugin :

A FuPlugin

prefix :

A string prefix that matches the quirks file basename, e.g. "dfu-quirks"

dev :

A GUsbDevice

Returns :

values from the database, or NULL if not found. [transfer none]

Since 1.0.1


fu_plugin_add_report_metadata ()

void                fu_plugin_add_report_metadata       (FuPlugin *plugin,
                                                         const gchar *key,
                                                         const gchar *value);

Sets any additional metadata to be included in the firmware report to aid debugging problems.

Any data included here will be sent to the metadata server after user confirmation.

plugin :

a FuPlugin

key :

a string, e.g. `FwupdateVersion`

value :

a string, e.g. `10`

fu_plugin_get_config_value ()

gchar *             fu_plugin_get_config_value          (FuPlugin *plugin,
                                                         const gchar *key);

Return the value of a key if it's been configured

plugin :

a FuPlugin

key :

A settings key

Since 1.0.6


fu_plugin_add_runtime_version ()

void                fu_plugin_add_runtime_version       (FuPlugin *plugin,
                                                         const gchar *component_id,
                                                         const gchar *version);

Sets a runtime version of a specific dependancy.

plugin :

A FuPlugin

component_id :

An AppStream component id, e.g. "org.gnome.Software"

version :

A version string, e.g. "1.2.3"

Since 1.0.7


fu_plugin_add_compile_version ()

void                fu_plugin_add_compile_version       (FuPlugin *plugin,
                                                         const gchar *component_id,
                                                         const gchar *version);

Sets a compile-time version of a specific dependancy.

plugin :

A FuPlugin

component_id :

An AppStream component id, e.g. "org.gnome.Software"

version :

A version string, e.g. "1.2.3"

Since 1.0.7