FuPlugin

FuPlugin — a daemon plugin

Functions

#define fu_plugin_get_flags()
#define fu_plugin_has_flag()
#define fu_plugin_add_flag()
#define fu_plugin_remove_flag()
const gchar * fu_plugin_get_name ()
FuPluginData * fu_plugin_get_data ()
FuPluginData * fu_plugin_alloc_data ()
gboolean fu_plugin_get_enabled ()
void fu_plugin_set_enabled ()
void fu_plugin_set_build_hash ()
GUsbContext * fu_plugin_get_usb_context ()
void fu_plugin_device_add ()
void fu_plugin_device_remove ()
void fu_plugin_device_register ()
void fu_plugin_request_recoldplug ()
void fu_plugin_security_changed ()
void fu_plugin_set_coldplug_delay ()
void fu_plugin_set_device_gtype ()
void fu_plugin_add_firmware_gtype ()
void fu_plugin_add_possible_quirk_key ()
gpointer fu_plugin_cache_lookup ()
void fu_plugin_cache_remove ()
void fu_plugin_cache_add ()
gboolean fu_plugin_check_hwid ()
gchar * fu_plugin_get_hwid_replace_value ()
GPtrArray * fu_plugin_get_devices ()
GPtrArray * fu_plugin_get_hwids ()
const gchar * fu_plugin_get_dmi_value ()
const gchar * fu_plugin_get_smbios_string ()
GBytes * fu_plugin_get_smbios_data ()
void fu_plugin_add_rule ()
void fu_plugin_add_udev_subsystem ()
FuQuirks * fu_plugin_get_quirks ()
const gchar * fu_plugin_lookup_quirk_by_id ()
guint64 fu_plugin_lookup_quirk_by_id_as_uint64 ()
void fu_plugin_add_report_metadata ()
gchar * fu_plugin_get_config_value ()
gboolean fu_plugin_get_config_value_boolean ()
void fu_plugin_add_runtime_version ()
void fu_plugin_add_compile_version ()
gboolean fu_plugin_has_custom_flag ()

Types and Values

Description

An object that represents a plugin run by the daemon.

See also: FuDevice

Functions

fu_plugin_get_flags()

#define fu_plugin_get_flags(p)			fwupd_plugin_get_flags(FWUPD_PLUGIN(p))

fu_plugin_has_flag()

#define fu_plugin_has_flag(p,f)			fwupd_plugin_has_flag(FWUPD_PLUGIN(p),f)

fu_plugin_add_flag()

#define fu_plugin_add_flag(p,f)			fwupd_plugin_add_flag(FWUPD_PLUGIN(p),f)

fu_plugin_remove_flag()

#define fu_plugin_remove_flag(p,f)		fwupd_plugin_remove_flag(FWUPD_PLUGIN(p),f)

fu_plugin_get_name ()

const gchar *
fu_plugin_get_name (FuPlugin *self);

Gets the plugin name.

Parameters

self

A FuPlugin

 

Returns

a plugin name, or NULL for unknown.

Since: 0.8.0


fu_plugin_get_data ()

FuPluginData *
fu_plugin_get_data (FuPlugin *self);

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

Parameters

self

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 *self,
                      gsize data_sz);

fu_plugin_get_enabled ()

gboolean
fu_plugin_get_enabled (FuPlugin *self);

fu_plugin_get_enabled is deprecated and should not be used in newly-written code.

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

Parameters

self

A FuPlugin

 

Returns

TRUE if the plugin is currently enabled.

Since: 0.8.0


fu_plugin_set_enabled ()

void
fu_plugin_set_enabled (FuPlugin *self,
                       gboolean enabled);

fu_plugin_set_enabled is deprecated and should not be used in newly-written code.

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

Parameters

self

A FuPlugin

 

enabled

the enabled value

 

Since: 0.8.0


fu_plugin_set_build_hash ()

void
fu_plugin_set_build_hash (FuPlugin *self,
                          const gchar *build_hash);

Sets the plugin build hash, typically a SHA256 checksum. All plugins must set the correct checksum to avoid the daemon being marked as tainted.

Parameters

self

A FuPlugin

 

build_hash

A checksum

 

Since: 1.2.4


fu_plugin_get_usb_context ()

GUsbContext *
fu_plugin_get_usb_context (FuPlugin *self);

This used to get the shared USB context that all plugins can use; it now returns NULL;

Parameters

self

A FuPlugin

 

Returns

a GUsbContext.

[transfer none]

Since: 0.8.0


fu_plugin_device_add ()

void
fu_plugin_device_add (FuPlugin *self,
                      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.

Parameters

self

A FuPlugin

 

device

A FuDevice

 

Since: 0.8.0


fu_plugin_device_remove ()

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

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

Parameters

self

A FuPlugin

 

device

A FuDevice

 

Since: 0.8.0


fu_plugin_device_register ()

void
fu_plugin_device_register (FuPlugin *self,
                           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 instance the coldplug should be ignored based on the metadata set from other plugins.

Parameters

self

A FuPlugin

 

device

A FuDevice

 

Since: 0.9.7


fu_plugin_request_recoldplug ()

void
fu_plugin_request_recoldplug (FuPlugin *self);

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

Parameters

self

A FuPlugin

 

Since: 0.8.0


fu_plugin_security_changed ()

void
fu_plugin_security_changed (FuPlugin *self);

Informs the daemon that the HSI state may have changed.

Parameters

self

A FuPlugin

 

Since: 1.5.0


fu_plugin_set_coldplug_delay ()

void
fu_plugin_set_coldplug_delay (FuPlugin *self,
                              guint duration);

Set the minimum time that should be waited in-between the call to fu_plugin_coldplug_prepare() and fu_plugin_coldplug(). This is usually going to be the minimum hardware initialization 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.

Parameters

self

A FuPlugin

 

duration

A delay in milliseconds

 

Since: 0.8.0


fu_plugin_set_device_gtype ()

void
fu_plugin_set_device_gtype (FuPlugin *self,
                            GType device_gtype);

Sets the device GType which is used when creating devices.

If this method is used then fu_plugin_backend_device_added() is not called, and instead the object is created in the daemon for the plugin.

Plugins can use this method only in fu_plugin_init()

Parameters

self

a FuPlugin

 

device_gtype

a GType FU_TYPE_DEVICE

 

Since: 1.3.3


fu_plugin_add_firmware_gtype ()

void
fu_plugin_add_firmware_gtype (FuPlugin *self,
                              const gchar *id,
                              GType gtype);

Adds a firmware GType which is used when creating devices. If id is not specified then it is guessed using the GType name.

Plugins can use this method only in fu_plugin_init()

Parameters

self

a FuPlugin

 

id

An optional string describing the type, e.g. "ihex".

[nullable]

gtype

a GType e.g. FU_TYPE_FOO_FIRMWARE

 

Since: 1.3.3


fu_plugin_add_possible_quirk_key ()

void
fu_plugin_add_possible_quirk_key (FuPlugin *self,
                                  const gchar *possible_key);

Adds a possible quirk key. If added by a plugin it should be namespaced using the plugin name, where possible.

Plugins can use this method only in fu_plugin_init()

Parameters

self

a FuPlugin

 

possible_key

A quirk string, e.g. DfuVersion

 

Since: 1.5.8


fu_plugin_cache_lookup ()

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

Finds an object in the per-plugin cache.

Parameters

self

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 *self,
                        const gchar *id);

Removes an object from the per-plugin cache.

Parameters

self

A FuPlugin

 

id

the key

 

Since: 0.8.0


fu_plugin_cache_add ()

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

Adds an object to the per-plugin cache.

Parameters

self

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 *self,
                      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.

Parameters

self

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_get_hwid_replace_value ()

gchar *
fu_plugin_get_hwid_replace_value (FuPlugin *self,
                                  const gchar *keys,
                                  GError **error);

Gets the replacement value for a specific key. All hardware IDs on a specific system can be shown using the fwupdmgr hwids command.

Parameters

self

A FuPlugin

 

keys

A key, e.g. HardwareID-3 or FU_HWIDS_KEY_PRODUCT_SKU

 

error

A GError or NULL

 

Returns

a string, or NULL for error.

[transfer full]

Since: 1.3.3


fu_plugin_get_devices ()

GPtrArray *
fu_plugin_get_devices (FuPlugin *self);

Returns all devices added by the plugin using fu_plugin_device_add() and not yet removed with fu_plugin_device_remove().

Parameters

self

A FuPlugin

 

Returns

devices.

[transfer none][element-type FuDevice]

Since: 1.5.6


fu_plugin_get_hwids ()

GPtrArray *
fu_plugin_get_hwids (FuPlugin *self);

Returns all the HWIDs defined in the system. All hardware IDs on a specific system can be shown using the fwupdmgr hwids command.

Parameters

self

A FuPlugin

 

Returns

An array of GUIDs.

[transfer none][element-type utf8]

Since: 1.1.1


fu_plugin_get_dmi_value ()

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

Gets a hardware DMI value.

Parameters

self

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 *self,
                             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

Parameters

self

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 *self,
                           guint8 structure_type);

Gets a hardware SMBIOS data.

Parameters

self

A FuPlugin

 

structure_type

A SMBIOS structure type, e.g. FU_SMBIOS_STRUCTURE_TYPE_BIOS

 

Returns

A GBytes, or NULL.

[transfer full]

Since: 0.9.8


fu_plugin_add_rule ()

void
fu_plugin_add_rule (FuPlugin *self,
                    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.

Parameters

self

a FuPlugin

 

rule

a FuPluginRule, e.g. FU_PLUGIN_RULE_CONFLICTS

 

name

a plugin name, e.g. upower

 

Since: 1.0.0


fu_plugin_add_udev_subsystem ()

void
fu_plugin_add_udev_subsystem (FuPlugin *self,
                              const gchar *subsystem);

Registers the udev subsystem to be watched by the daemon.

Plugins can use this method only in fu_plugin_init()

Parameters

self

a FuPlugin

 

subsystem

a subsystem name, e.g. pciport

 

Since: 1.1.2


fu_plugin_get_quirks ()

FuQuirks *
fu_plugin_get_quirks (FuPlugin *self);

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

Parameters

self

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 *self,
                              const gchar *group,
                              const gchar *key);

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

Parameters

self

A FuPlugin

 

group

A string, e.g. "DfuFlags"

 

key

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

 

Returns

values from the database, or NULL if not found.

[transfer none]

Since: 1.0.1


fu_plugin_lookup_quirk_by_id_as_uint64 ()

guint64
fu_plugin_lookup_quirk_by_id_as_uint64
                               (FuPlugin *self,
                                const gchar *group,
                                const gchar *key);

Looks up an entry in the hardware database using a string key, returning an integer value. Values are assumed base 10, unless prefixed with "0x" where they are parsed as base 16.

Parameters

self

A FuPlugin

 

group

A string, e.g. "DfuFlags"

 

key

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

 

Returns

guint64 id or 0 if not found

Since: 1.1.2


fu_plugin_add_report_metadata ()

void
fu_plugin_add_report_metadata (FuPlugin *self,
                               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.

Parameters

self

a FuPlugin

 

key

a string, e.g. FwupdateVersion

 

value

a string, e.g. 10

 

Since: 1.0.4


fu_plugin_get_config_value ()

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

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

Parameters

self

a FuPlugin

 

key

A settings key

 

Since: 1.0.6


fu_plugin_get_config_value_boolean ()

gboolean
fu_plugin_get_config_value_boolean (FuPlugin *self,
                                    const gchar *key);

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

Parameters

self

a FuPlugin

 

key

A settings key

 

Returns

TRUE if the value is true (case insensitive), FALSE otherwise

Since: 1.4.0


fu_plugin_add_runtime_version ()

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

Sets a runtime version of a specific dependency.

Parameters

self

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 *self,
                               const gchar *component_id,
                               const gchar *version);

Sets a compile-time version of a specific dependency.

Parameters

self

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_has_custom_flag ()

gboolean
fu_plugin_has_custom_flag (FuPlugin *self,
                           const gchar *flag);

Returns if a per-plugin HwId custom flag exists, typically added from a DMI quirk.

Parameters

self

A FuPlugin

 

flag

A custom text flag, specific to the plugin, e.g. uefi-force-enable

 

Returns

TRUE if the quirk entry exists

Since: 1.3.1

Types and Values

FU_TYPE_PLUGIN

#define FU_TYPE_PLUGIN (fu_plugin_get_type ())

struct FuPluginClass

struct FuPluginClass {
	FwupdPluginClass parent_class;
	/* signals */
	void		 (* device_added)		(FuPlugin *self,
							 FuDevice *device);
	void		 (* device_removed)		(FuPlugin *self,
							 FuDevice *device);
	void		 (* status_changed)		(FuPlugin *self,
							 FwupdStatus	 status);
	void		 (* percentage_changed)		(FuPlugin *self,
							 guint		 percentage);
	void		 (* recoldplug)			(FuPlugin *self);
	void		 (* set_coldplug_delay)		(FuPlugin *self,
							 guint		 duration);
	void		 (* device_register)		(FuPlugin *self,
							 FuDevice *device);
	gboolean	 (* check_supported)		(FuPlugin *self,
							 const gchar *guid);
	void		 (* rules_changed)		(FuPlugin *self);
	gboolean	 (* add_firmware_gtype)		(FuPlugin *self,
							 const gchar *id,
							 GType		 gtype);
	void		 (* security_changed)		(FuPlugin *self);
};

enum FuPluginVerifyFlags

Flags used when verifying, currently unused.

Members

FU_PLUGIN_VERIFY_FLAG_NONE

No flags set

 

enum FuPluginRule

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

Members

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

 

FU_PLUGIN_RULE_BETTER_THAN

Is better than another plugin

 

FU_PLUGIN_RULE_INHIBITS_IDLE

The plugin inhibits the idle shutdown

 

FU_PLUGIN_RULE_METADATA_SOURCE

Uses another plugin as a source of report metadata

 

FuPluginData

typedef struct FuPluginData FuPluginData;

FuPlugin

typedef struct _FuPlugin FuPlugin;