FuPlugin: fwupd Reference Manual

## FuPlugin FuPlugin — a daemon plugin |

## Functions

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 ()
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_set_coldplug_delay ()
gpointer | fu_plugin_cache_lookup ()
void | fu_plugin_cache_remove ()
void | fu_plugin_cache_add ()
gboolean | fu_plugin_check_hwid ()
GPtrArray * | fu_plugin_get_hwids ()
gboolean | fu_plugin_check_supported ()
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 ()
void | fu_plugin_add_runtime_version ()
void | fu_plugin_add_compile_version ()

## Types and Values

#define | FU_TYPE_PLUGIN
struct | FuPluginClass
enum | FuPluginVerifyFlags
enum | FuPluginRule
typedef | FuPluginData
| FuPlugin

## Description

An object that represents a plugin run by the daemon.

See also: FuDevice

## Functions

### 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);

Allocates the per-plugin allocated private data.

#### Parameters

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

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);

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

    GUsbContext *
    fu_plugin_get_usb_context (FuPlugin *self);

Gets the shared USB context that all plugins can use.

#### 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 intance 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_set_coldplug_delay ()

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

#### Parameters

self | A FuPlugin |
duration | A delay in milliseconds |

Since: 0.8.0

### 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_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 utf-8]

Since: 1.1.1

### fu_plugin_check_supported ()

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

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

#### Parameters

self | 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 *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 none]

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` |

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

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

value from the database, or 0 if not found.

[transfer none]

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` |

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

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

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

## Types and Values

### FU_TYPE_PLUGIN

    #define FU_TYPE_PLUGIN (fu_plugin_get_type ())

### struct FuPluginClass

    struct FuPluginClass {
    	GObjectClass	 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);
    };

### 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_REQUIRES_QUIRK | Requires a specific quirk |
FU_PLUGIN_RULE_BETTER_THAN | Is better than another plugin |
FU_PLUGIN_RULE_INHIBITS_IDLE | The plugin inhibits the idle shutdown |

### FuPluginData

    typedef struct FuPluginData FuPluginData;

### FuPlugin

    typedef struct _FuPlugin FuPlugin;