FwupdClient

FwupdClient — a way of interfacing with the daemon

Functions

FwupdClient * fwupd_client_new ()
gboolean fwupd_client_connect ()
GPtrArray * fwupd_client_get_devices ()
GPtrArray * fwupd_client_get_history ()
GPtrArray * fwupd_client_get_releases ()
GPtrArray * fwupd_client_get_downgrades ()
GPtrArray * fwupd_client_get_upgrades ()
GPtrArray * fwupd_client_get_details ()
gboolean fwupd_client_verify ()
gboolean fwupd_client_verify_update ()
gboolean fwupd_client_unlock ()
gboolean fwupd_client_modify_config ()
gboolean fwupd_client_activate ()
gboolean fwupd_client_clear_results ()
FwupdDevice * fwupd_client_get_results ()
FwupdDevice * fwupd_client_get_device_by_id ()
GPtrArray * fwupd_client_get_devices_by_guid ()
gboolean fwupd_client_install ()
gboolean fwupd_client_install_bytes ()
gboolean fwupd_client_install_release ()
gboolean fwupd_client_update_metadata ()
gboolean fwupd_client_update_metadata_bytes ()
gboolean fwupd_client_refresh_remote ()
gboolean fwupd_client_modify_remote ()
gboolean fwupd_client_modify_device ()
FwupdStatus fwupd_client_get_status ()
gboolean fwupd_client_get_tainted ()
gboolean fwupd_client_get_daemon_interactive ()
guint fwupd_client_get_percentage ()
const gchar * fwupd_client_get_daemon_version ()
const gchar * fwupd_client_get_host_product ()
const gchar * fwupd_client_get_host_machine_id ()
GPtrArray * fwupd_client_get_remotes ()
FwupdRemote * fwupd_client_get_remote_by_id ()
gchar ** fwupd_client_get_approved_firmware ()
gboolean fwupd_client_set_approved_firmware ()
gchar * fwupd_client_self_sign ()
gboolean fwupd_client_set_feature_flags ()
void fwupd_client_set_user_agent ()
void fwupd_client_set_user_agent_for_package ()
GBytes * fwupd_client_download_bytes ()
GBytes * fwupd_client_upload_bytes ()
gboolean fwupd_client_ensure_networking ()

Types and Values

Description

An object that allows client code to call the daemon methods synchronously.

See also: FwupdDevice

Functions

fwupd_client_new ()

FwupdClient *
fwupd_client_new (void);

Creates a new client.

Returns

a new FwupdClient

Since: 0.7.0


fwupd_client_connect ()

gboolean
fwupd_client_connect (FwupdClient *client,
                      GCancellable *cancellable,
                      GError **error);

Sets up the client ready for use. Most other methods call this for you, and do you only need to call this if you are just watching the client.

Parameters

client

A FwupdClient

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 0.7.1


fwupd_client_get_devices ()

GPtrArray *
fwupd_client_get_devices (FwupdClient *client,
                          GCancellable *cancellable,
                          GError **error);

Gets all the devices registered with the daemon.

Parameters

client

A FwupdClient

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

results.

[element-type FwupdDevice][transfer container]

Since: 0.9.2


fwupd_client_get_history ()

GPtrArray *
fwupd_client_get_history (FwupdClient *client,
                          GCancellable *cancellable,
                          GError **error);

Gets all the history.

Parameters

client

A FwupdClient

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

results.

[element-type FwupdDevice][transfer container]

Since: 1.0.4


fwupd_client_get_releases ()

GPtrArray *
fwupd_client_get_releases (FwupdClient *client,
                           const gchar *device_id,
                           GCancellable *cancellable,
                           GError **error);

Gets all the releases for a specific device

Parameters

client

A FwupdClient

 

device_id

the device ID

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

results.

[element-type FwupdRelease][transfer container]

Since: 0.9.3


fwupd_client_get_downgrades ()

GPtrArray *
fwupd_client_get_downgrades (FwupdClient *client,
                             const gchar *device_id,
                             GCancellable *cancellable,
                             GError **error);

Gets all the downgrades for a specific device.

Parameters

client

A FwupdClient

 

device_id

the device ID

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

results.

[element-type FwupdRelease][transfer container]

Since: 0.9.8


fwupd_client_get_upgrades ()

GPtrArray *
fwupd_client_get_upgrades (FwupdClient *client,
                           const gchar *device_id,
                           GCancellable *cancellable,
                           GError **error);

Gets all the upgrades for a specific device.

Parameters

client

A FwupdClient

 

device_id

the device ID

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

results.

[element-type FwupdRelease][transfer container]

Since: 0.9.8


fwupd_client_get_details ()

GPtrArray *
fwupd_client_get_details (FwupdClient *client,
                          const gchar *filename,
                          GCancellable *cancellable,
                          GError **error);

Gets details about a specific firmware file.

Parameters

client

A FwupdClient

 

filename

the firmware filename, e.g. firmware.cab

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

an array of results.

[transfer container][element-type FwupdDevice]

Since: 1.0.0


fwupd_client_verify ()

gboolean
fwupd_client_verify (FwupdClient *client,
                     const gchar *device_id,
                     GCancellable *cancellable,
                     GError **error);

Verify a specific device.

Parameters

client

A FwupdClient

 

device_id

the device ID

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for verification success

Since: 0.7.0


fwupd_client_verify_update ()

gboolean
fwupd_client_verify_update (FwupdClient *client,
                            const gchar *device_id,
                            GCancellable *cancellable,
                            GError **error);

Update the verification record for a specific device.

Parameters

client

A FwupdClient

 

device_id

the device ID

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for verification success

Since: 0.8.0


fwupd_client_unlock ()

gboolean
fwupd_client_unlock (FwupdClient *client,
                     const gchar *device_id,
                     GCancellable *cancellable,
                     GError **error);

Unlocks a specific device so firmware can be read or wrote.

Parameters

client

A FwupdClient

 

device_id

the device ID

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 0.7.0


fwupd_client_modify_config ()

gboolean
fwupd_client_modify_config (FwupdClient *client,
                            const gchar *key,
                            const gchar *value,
                            GCancellable *cancellable,
                            GError **error);

Modifies a daemon config option. The daemon will only respond to this request with proper permissions

Parameters

client

A FwupdClient

 

key

key, e.g. BlacklistPlugins

 

value

value, e.g. *

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 1.2.8


fwupd_client_activate ()

gboolean
fwupd_client_activate (FwupdClient *client,
                       GCancellable *cancellable,
                       const gchar *device_id,
                       GError **error);

Activates up a device, which normally means the device switches to a new firmware version. This should only be called when data loss cannot occur.

Parameters

client

A FwupdClient

 

cancellable

the GCancellable, or NULL

 

device_id

a device

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 1.2.6


fwupd_client_clear_results ()

gboolean
fwupd_client_clear_results (FwupdClient *client,
                            const gchar *device_id,
                            GCancellable *cancellable,
                            GError **error);

Clears the results for a specific device.

Parameters

client

A FwupdClient

 

device_id

the device ID

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 0.7.0


fwupd_client_get_results ()

FwupdDevice *
fwupd_client_get_results (FwupdClient *client,
                          const gchar *device_id,
                          GCancellable *cancellable,
                          GError **error);

Gets the results of a previous firmware update for a specific device.

Parameters

client

A FwupdClient

 

device_id

the device ID

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

a FwupdDevice, or NULL for failure.

[transfer full]

Since: 0.7.0


fwupd_client_get_device_by_id ()

FwupdDevice *
fwupd_client_get_device_by_id (FwupdClient *client,
                               const gchar *device_id,
                               GCancellable *cancellable,
                               GError **error);

Gets a device by it's device ID.

Parameters

client

A FwupdClient

 

device_id

the device ID, e.g. usb:00:01:03:03

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

a FwupdDevice or NULL.

[transfer full]

Since: 0.9.3


fwupd_client_get_devices_by_guid ()

GPtrArray *
fwupd_client_get_devices_by_guid (FwupdClient *client,
                                  const gchar *guid,
                                  GCancellable *cancellable,
                                  GError **error);

Gets any devices that provide a specific GUID. An error is returned if no devices contains this GUID.

Parameters

client

A FwupdClient

 

guid

the GUID, e.g. e22c4520-43dc-5bb3-8245-5787fead9b63

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

devices or NULL.

[element-type FwupdDevice][transfer container]

Since: 1.4.1


fwupd_client_install ()

gboolean
fwupd_client_install (FwupdClient *client,
                      const gchar *device_id,
                      const gchar *filename,
                      FwupdInstallFlags install_flags,
                      GCancellable *cancellable,
                      GError **error);

Install a file onto a specific device.

Parameters

client

A FwupdClient

 

device_id

the device ID

 

filename

the filename to install

 

install_flags

the FwupdInstallFlags, e.g. FWUPD_INSTALL_FLAG_ALLOW_REINSTALL

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 0.7.0


fwupd_client_install_bytes ()

gboolean
fwupd_client_install_bytes (FwupdClient *client,
                            const gchar *device_id,
                            GBytes *bytes,
                            FwupdInstallFlags install_flags,
                            GCancellable *cancellable,
                            GError **error);

Install firmware onto a specific device.

Parameters

client

A FwupdClient

 

device_id

the device ID

 

bytes

GBytes

 

install_flags

the FwupdInstallFlags, e.g. FWUPD_INSTALL_FLAG_ALLOW_REINSTALL

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 1.4.5


fwupd_client_install_release ()

gboolean
fwupd_client_install_release (FwupdClient *client,
                              FwupdDevice *device,
                              FwupdRelease *release,
                              FwupdInstallFlags install_flags,
                              GCancellable *cancellable,
                              GError **error);

Installs a new release on a device, downloading the firmware if required.

Parameters

client

A FwupdClient

 

device

A FwupdDevice

 

release

A FwupdRelease

 

install_flags

the FwupdInstallFlags, e.g. FWUPD_INSTALL_FLAG_ALLOW_REINSTALL

 

cancellable

A GCancellable, or NULL

 

error

A GError, or NULL

 

Returns

TRUE for success

Since: 1.4.5


fwupd_client_update_metadata ()

gboolean
fwupd_client_update_metadata (FwupdClient *client,
                              const gchar *remote_id,
                              const gchar *metadata_fn,
                              const gchar *signature_fn,
                              GCancellable *cancellable,
                              GError **error);

Updates the metadata. This allows a session process to download the metadata and metadata signing file to be passed into the daemon to be checked and parsed.

The remote_id allows the firmware to be tagged so that the remote can be matched when the firmware is downloaded.

Parameters

client

A FwupdClient

 

remote_id

the remote ID, e.g. lvfs-testing

 

metadata_fn

the XML metadata filename

 

signature_fn

the GPG signature file

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 1.0.0


fwupd_client_update_metadata_bytes ()

gboolean
fwupd_client_update_metadata_bytes (FwupdClient *client,
                                    const gchar *remote_id,
                                    GBytes *metadata,
                                    GBytes *signature,
                                    GCancellable *cancellable,
                                    GError **error);

Updates the metadata. This allows a session process to download the metadata and metadata signing file to be passed into the daemon to be checked and parsed.

The remote_id allows the firmware to be tagged so that the remote can be matched when the firmware is downloaded.

Parameters

client

A FwupdClient

 

remote_id

remote ID, e.g. lvfs-testing

 

metadata

XML metadata data

 

signature

signature data

 

cancellable

GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 1.4.5


fwupd_client_refresh_remote ()

gboolean
fwupd_client_refresh_remote (FwupdClient *client,
                             FwupdRemote *remote,
                             GCancellable *cancellable,
                             GError **error);

Refreshes a remote by downloading new metadata.

Parameters

client

A FwupdClient

 

remote

A FwupdRemote

 

cancellable

A GCancellable, or NULL

 

error

A GError, or NULL

 

Returns

TRUE for success

Since: 1.4.5


fwupd_client_modify_remote ()

gboolean
fwupd_client_modify_remote (FwupdClient *client,
                            const gchar *remote_id,
                            const gchar *key,
                            const gchar *value,
                            GCancellable *cancellable,
                            GError **error);

Modifies a system remote in a specific way.

NOTE: User authentication may be required to complete this action.

Parameters

client

A FwupdClient

 

remote_id

the remote ID, e.g. lvfs-testing

 

key

the key, e.g. Enabled

 

value

the key, e.g. true

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 0.9.8


fwupd_client_modify_device ()

gboolean
fwupd_client_modify_device (FwupdClient *client,
                            const gchar *device_id,
                            const gchar *key,
                            const gchar *value,
                            GCancellable *cancellable,
                            GError **error);

Modifies a device in a specific way. Not all properties on the FwupdDevice are settable by the client, and some may have other restrictions on value .

NOTE: User authentication may be required to complete this action.

Parameters

client

A FwupdClient

 

device_id

the device ID

 

key

the key, e.g. Flags

 

value

the key, e.g. reported

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 1.0.4


fwupd_client_get_status ()

FwupdStatus
fwupd_client_get_status (FwupdClient *client);

Gets the last returned status value.

Parameters

client

A FwupdClient

 

Returns

a FwupdStatus, or FWUPD_STATUS_UNKNOWN for unknown.

Since: 0.7.3


fwupd_client_get_tainted ()

gboolean
fwupd_client_get_tainted (FwupdClient *client);

Gets if the daemon has been tainted by 3rd party code.

Parameters

client

A FwupdClient

 

Returns

TRUE if the daemon is unsupported

Since: 1.2.4


fwupd_client_get_daemon_interactive ()

gboolean
fwupd_client_get_daemon_interactive (FwupdClient *client);

Gets if the daemon is running in an interactive terminal.

Parameters

client

A FwupdClient

 

Returns

TRUE if the daemon is running in an interactive terminal

Since: 1.3.4


fwupd_client_get_percentage ()

guint
fwupd_client_get_percentage (FwupdClient *client);

Gets the last returned percentage value.

Parameters

client

A FwupdClient

 

Returns

a percentage, or 0 for unknown.

Since: 0.7.3


fwupd_client_get_daemon_version ()

const gchar *
fwupd_client_get_daemon_version (FwupdClient *client);

Gets the daemon version number.

Parameters

client

A FwupdClient

 

Returns

a string, or NULL for unknown.

Since: 0.9.6


fwupd_client_get_host_product ()

const gchar *
fwupd_client_get_host_product (FwupdClient *client);

Gets the string that represents the host running fwupd

Parameters

client

A FwupdClient

 

Returns

a string, or NULL for unknown.

Since: 1.3.1


fwupd_client_get_host_machine_id ()

const gchar *
fwupd_client_get_host_machine_id (FwupdClient *client);

Gets the string that represents the host machine ID

Parameters

client

A FwupdClient

 

Returns

a string, or NULL for unknown.

Since: 1.3.2


fwupd_client_get_remotes ()

GPtrArray *
fwupd_client_get_remotes (FwupdClient *client,
                          GCancellable *cancellable,
                          GError **error);

Gets the list of remotes that have been configured for the system.

Parameters

client

A FwupdClient

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

list of remotes, or NULL.

[element-type FwupdRemote][transfer container]

Since: 0.9.3


fwupd_client_get_remote_by_id ()

FwupdRemote *
fwupd_client_get_remote_by_id (FwupdClient *client,
                               const gchar *remote_id,
                               GCancellable *cancellable,
                               GError **error);

Gets a specific remote that has been configured for the system.

Parameters

client

A FwupdClient

 

remote_id

the remote ID, e.g. lvfs-testing

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

a FwupdRemote, or NULL if not found.

[transfer full]

Since: 0.9.3


fwupd_client_get_approved_firmware ()

gchar **
fwupd_client_get_approved_firmware (FwupdClient *client,
                                    GCancellable *cancellable,
                                    GError **error);

Gets the list of approved firmware.

Parameters

client

A FwupdClient

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

list of remotes, or NULL.

[transfer full]

Since: 1.2.6


fwupd_client_set_approved_firmware ()

gboolean
fwupd_client_set_approved_firmware (FwupdClient *client,
                                    gchar **checksums,
                                    GCancellable *cancellable,
                                    GError **error);

Sets the list of approved firmware.

Parameters

client

A FwupdClient

 

checksums

Array of checksums

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 1.2.6


fwupd_client_self_sign ()

gchar *
fwupd_client_self_sign (FwupdClient *client,
                        const gchar *value,
                        FwupdSelfSignFlags flags,
                        GCancellable *cancellable,
                        GError **error);

Signs the data using the client self-signed certificate.

Parameters

client

A FwupdClient

 

value

A string to sign, typically a JSON blob

 

flags

FwupdSelfSignFlags, e.g. FWUPD_SELF_SIGN_FLAG_ADD_TIMESTAMP

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 1.2.6


fwupd_client_set_feature_flags ()

gboolean
fwupd_client_set_feature_flags (FwupdClient *client,
                                FwupdFeatureFlags feature_flags,
                                GCancellable *cancellable,
                                GError **error);

Sets the features the client supports. This allows firmware to depend on specific front-end features, for instance showing the user an image on how to detach the hardware.

Clients can call this none or multiple times.

Parameters

client

A FwupdClient

 

feature_flags

FwupdFeatureFlags, e.g. FWUPD_FEATURE_FLAG_UPDATE_TEXT

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 1.4.5


fwupd_client_set_user_agent ()

void
fwupd_client_set_user_agent (FwupdClient *client,
                             const gchar *user_agent);

Manually sets the user agent that is used for downloading. The user agent should contain the runtime version of fwupd somewhere in the provided string.

Parameters

client

A FwupdClient

 

user_agent

the user agent ID, e.g. gnome-software/3.34.1

 

Since: 1.4.5


fwupd_client_set_user_agent_for_package ()

void
fwupd_client_set_user_agent_for_package
                               (FwupdClient *client,
                                const gchar *package_name,
                                const gchar *package_version);

Builds a user-agent to use for the download.

Supplying harmless details to the server means it knows more about each client. This allows the web service to respond in a different way, for instance sending a different metadata file for old versions of fwupd, or returning an error for Solaris machines.

Before freaking out about theoretical privacy implications, much more data than this is sent to each and every website you visit.

Parameters

client

A FwupdClient

 

package_name

client program name, e.g. "gnome-software"

 

package_version

client program version, e.g. "3.28.1"

 

Since: 1.4.5


fwupd_client_download_bytes ()

GBytes *
fwupd_client_download_bytes (FwupdClient *client,
                             const gchar *url,
                             FwupdClientDownloadFlags flags,
                             GCancellable *cancellable,
                             GError **error);

Downloads data from a remote server. The fwupd_client_set_user_agent() function should be called before this method is used.

Parameters

client

A FwupdClient

 

url

the remote URL

 

flags

FwupdClientDownloadFlags, e.g. FWUPD_CLIENT_DOWNLOAD_FLAG_NONE

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

downloaded data, or NULL for error.

[transfer full]

Since: 1.4.5


fwupd_client_upload_bytes ()

GBytes *
fwupd_client_upload_bytes (FwupdClient *client,
                           const gchar *url,
                           const gchar *payload,
                           const gchar *signature,
                           FwupdClientUploadFlags flags,
                           GCancellable *cancellable,
                           GError **error);

Uploads data to a remote server. The fwupd_client_set_user_agent() function should be called before this method is used.

Parameters

client

A FwupdClient

 

url

the remote URL

 

payload

payload string

 

signature

signature string.

[nullable]

flags

FwupdClientDownloadFlags, e.g. FWUPD_CLIENT_DOWNLOAD_FLAG_NONE

 

cancellable

the GCancellable, or NULL

 

error

the GError, or NULL

 

Returns

downloaded data, or NULL for error.

[transfer full]

Since: 1.4.5


fwupd_client_ensure_networking ()

gboolean
fwupd_client_ensure_networking (FwupdClient *client,
                                GError **error);

Sets up the client networking support ready for use. Most other download and upload methods call this automatically, and do you only need to call this if the session is being used outside the FwupdClient.

Parameters

client

A FwupdClient

 

error

the GError, or NULL

 

Returns

TRUE for success

Since: 1.4.5

Types and Values

FWUPD_TYPE_CLIENT

#define FWUPD_TYPE_CLIENT (fwupd_client_get_type ())

struct FwupdClientClass

struct FwupdClientClass {
	GObjectClass		 parent_class;
	void			(*changed)		(FwupdClient *client);
	void			(*status_changed) (FwupdClient *client,
							 FwupdStatus	 status);
	void			(*device_added)		(FwupdClient *client,
							 FwupdDevice *result);
	void			(*device_removed) (FwupdClient *client,
							 FwupdDevice *result);
	void			(*device_changed) (FwupdClient *client,
							 FwupdDevice *result);
};

enum FwupdClientDownloadFlags

The options to use for downloading.

Members

FWUPD_CLIENT_DOWNLOAD_FLAG_NONE

No flags set

 

enum FwupdClientUploadFlags

The options to use for uploading.

Members

FWUPD_CLIENT_UPLOAD_FLAG_NONE

No flags set

 

FWUPD_CLIENT_UPLOAD_FLAG_ALWAYS_MULTIPART

Always use multipart/form-data

 

FwupdClient

typedef struct _FwupdClient FwupdClient;