FuPlugin

FuPlugin

Functions

Types and Values

Description

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

FuContext *
fu_plugin_get_context (FuPlugin *self);

Gets the context for a plugin.

Parameters

self

a FuPlugin

 

Returns

a FuContext or NULL if not set.

[transfer none]

Since: 1.6.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.

Parameters

self

a FuPlugin

 

device

a device

 

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 device

 

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 device

 

Since: 0.9.7


fu_plugin_add_device_gtype ()

void
fu_plugin_add_device_gtype (FuPlugin *self,
                            GType device_gtype);

Adds 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, e.g. FU_TYPE_DEVICE

 

Since: 1.6.0


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_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.6.2


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_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_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 plugin rule, e.g. FU_PLUGIN_RULE_CONFLICTS

 

name

a plugin name, e.g. upower

 

Since: 1.0.0


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

gboolean
fu_plugin_set_secure_config_value (FuPlugin *self,
                                   const gchar *key,
                                   const gchar *value,
                                   GError **error);

Sets a plugin config file value and updates file so that non-privileged users cannot read it.

Parameters

self

a FuPlugin

 

key

a settings key

 

value

a settings value.

[nullable]

error

optional return location for an error.

[nullable]

Returns

TRUE for success

Since: 1.7.4


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

gboolean
fu_plugin_set_config_value (FuPlugin *self,
                            const gchar *key,
                            const gchar *value,
                            GError **error);

Sets a plugin config value.

Parameters

self

a FuPlugin

 

key

a settings key

 

value

a settings value.

[nullable]

error

optional return location for an error.

[nullable]

Returns

TRUE for success

Since: 1.7.0


fu_plugin_has_custom_flag ()

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

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

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 (*device_register)(FuPlugin *self, FuDevice *device);
	gboolean (*check_supported)(FuPlugin *self, const gchar *guid);
	void (*rules_changed)(FuPlugin *self);
	void (*config_changed)(FuPlugin *self);
};

enum FuPluginVerifyFlags

Flags used when verifying, currently unused.

Members

FU_PLUGIN_VERIFY_FLAG_NONE

No flags set

 

FuPluginVfuncs

typedef struct {
	/**
	 * build_hash:
	 *
	 * Sets the plugin build hash which must be set to avoid tainting the engine.
	 *
	 * Since: 1.7.2
	 **/
	const gchar *build_hash;
	/**
	 * init:
	 * @self: A #FuPlugin
	 *
	 * Initializes the plugin.
	 * Sets up any static data structures for the plugin.
	 * Most plugins should call fu_plugin_set_build_hash in here.
	 *
	 * Since: 1.7.2
	 **/
	void (*init)(FuPlugin *self);
	/**
	 * destroy:
	 * @self: a plugin
	 *
	 * Destroys the plugin.
	 * Any allocated memory should be freed here.
	 *
	 * Since: 1.7.2
	 **/
	void (*destroy)(FuPlugin *self);
	/**
	 * startup:
	 * @self: a #FuPlugin
	 * @error: (nullable): optional return location for an error
	 *
	 * Tries to start the plugin.
	 * Returns: TRUE for success or FALSE for failure.
	 *
	 * Any plugins not intended for the system or that have failure communicating
	 * with the device should return FALSE.
	 * Any allocated memory should be freed here.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*startup)(FuPlugin *self, GError **error);
	/**
	 * coldplug:
	 * @self: a #FuPlugin
	 * @error: (nullable): optional return location for an error
	 *
	 * Probes for devices.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*coldplug)(FuPlugin *self, GError **error);
	/**
	 * device_created
	 * @self: a #FuPlugin
	 * @dev: a device
	 * @error: (nullable): optional return location for an error
	 *
	 * Function run when the subclassed device has been created.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*device_created)(FuPlugin *self, FuDevice *device, GError **error);
	/**
	 * device_registered
	 * @self: a #FuPlugin
	 * @dev: a device
	 *
	 * Function run when device registered from another plugin.
	 *
	 * Since: 1.7.2
	 **/
	void (*device_registered)(FuPlugin *self, FuDevice *device);
	/**
	 * device_added
	 * @self: a #FuPlugin
	 * @dev: a device
	 *
	 * Function run when the subclassed device has been added.
	 *
	 * Since: 1.7.2
	 **/
	void (*device_added)(FuPlugin *self, FuDevice *device);
	/**
	 * verify:
	 * @self: a #FuPlugin
	 * @dev: a device
	 * @flags: verify flags
	 * @error: (nullable): optional return location for an error
	 *
	 * Verifies the firmware on the device matches the value stored in the database
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*verify)(FuPlugin *self,
			   FuDevice *device,
			   FuPluginVerifyFlags flags,
			   GError **error);
	/**
	 * get_results:
	 * @self: a #FuPlugin
	 * @dev: a device
	 * @error: (nullable): optional return location for an error
	 *
	 * Obtains historical update results for the device.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*get_results)(FuPlugin *self, FuDevice *device, GError **error);
	/**
	 * clear_results:
	 * @self: a #FuPlugin
	 * @dev: a device
	 * @error: (nullable): optional return location for an error
	 *
	 * Clears stored update results for the device.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*clear_results)(FuPlugin *self, FuDevice *device, GError **error);
	/**
	 * backend_device_added
	 * @self: a #FuPlugin
	 * @device: a device
	 * @error: (nullable): optional return location for an error
	 *
	 * Function to run after a device is added by a backend, e.g. by USB or Udev.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*backend_device_added)(FuPlugin *self, FuDevice *device, GError **error);
	/**
	 * backend_device_changed
	 * @self: a #FuPlugin
	 * @device: a device
	 * @error: (nullable): optional return location for an error
	 *
	 * Function run when the device changed.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*backend_device_changed)(FuPlugin *self, FuDevice *device, GError **error);
	/**
	 * backend_device_removed
	 * @self: a #FuPlugin
	 * @device: a device
	 * @error: (nullable): optional return location for an error
	 *
	 * Function to run when device is physically removed.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*backend_device_removed)(FuPlugin *self, FuDevice *device, GError **error);
	/**
	 * add_security_attrs
	 * @self: a #FuPlugin
	 * @attrs: a security attribute
	 *
	 * Function that asks plugins to add Host Security Attributes.
	 *
	 * Since: 1.7.2
	 **/
	void (*add_security_attrs)(FuPlugin *self, FuSecurityAttrs *attrs);
	/**
	 * write_firmware:
	 * @self: a #FuPlugin
	 * @dev: a device
	 * @blob_fw: a data blob
	 * @progress: a #FuProgress
	 * @flags: install flags
	 * @error: (nullable): optional return location for an error
	 *
	 * Updates the firmware on the device with blob_fw
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*write_firmware)(FuPlugin *self,
				   FuDevice *device,
				   GBytes *blob_fw,
				   FuProgress *progress,
				   FwupdInstallFlags flags,
				   GError **error);
	/**
	 * unlock:
	 * @self: a #FuPlugin
	 * @dev: a device
	 * @error: (nullable): optional return location for an error
	 *
	 * Unlocks the device for writes.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*unlock)(FuPlugin *self, FuDevice *device, GError **error);
	/**
	 * activate:
	 * @self: a #FuPlugin
	 * @dev: a device
	 * @error: (nullable): optional return location for an error
	 *
	 * Activates the new firmware on the device.
	 *
	 * This is intended for devices that it is not safe to immediately activate
	 * the firmware.  It may be called at a more convenient time instead.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*activate)(FuPlugin *self,
			     FuDevice *device,
			     FuProgress *progress,
			     GError **error);
	/**
	 * attach:
	 * @self: a #FuPlugin
	 * @dev: a device
	 * @error: (nullable): optional return location for an error
	 *
	 * Swaps the device from bootloader mode to runtime mode.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*attach)(FuPlugin *self, FuDevice *device, FuProgress *progress, GError **error);
	/**
	 * detach:
	 * @self: a #FuPlugin
	 * @dev: a device
	 * @error: (nullable): optional return location for an error
	 *
	 * Swaps the device from runtime mode to bootloader mode.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*detach)(FuPlugin *self, FuDevice *device, FuProgress *progress, GError **error);
	/**
	 * prepare:
	 * @self: a #FuPlugin
	 * @dev: a device
	 * @flags: install flags
	 * @error: (nullable): optional return location for an error
	 *
	 * Prepares the device to receive an update.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*prepare)(FuPlugin *self,
			    FuDevice *device,
			    FwupdInstallFlags flags,
			    GError **error);
	/**
	 * cleanup
	 * @self: a #FuPlugin
	 * @dev: a device
	 * @flags: install flags
	 * @error: (nullable): optional return location for an error
	 *
	 * Cleans up the device after receiving an update.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*cleanup)(FuPlugin *self,
			    FuDevice *device,
			    FwupdInstallFlags flags,
			    GError **error);
	/**
	 * composite_prepare
	 * @self: a #FuPlugin
	 * @devices: (element-type FuDevice): array of devices
	 * @error: (nullable): optional return location for an error
	 *
	 * Function run before updating group of composite devices.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*composite_prepare)(FuPlugin *self, GPtrArray *devices, GError **error);
	/**
	 * composite_cleanup
	 * @self: a #FuPlugin
	 * @devices: (element-type FuDevice): array of devices
	 * @error: (nullable): optional return location for an error
	 *
	 * Function run after updating group of composite devices.
	 *
	 * Since: 1.7.2
	 **/
	gboolean (*composite_cleanup)(FuPlugin *self, GPtrArray *devices, GError **error);
} FuPluginVfuncs;

The virtual functions that are implemented by the plugins.


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;

The plugin-allocated private data.


FuPlugin

typedef struct _FuPlugin FuPlugin;

A plugin which is used by fwupd to enumerate and update devices.

See also: [classFuDevice ], [classFwupd.Plugin ]