Functions

  byte_array_append_uint16 (array, data, endian)
  byte_array_append_uint32 (array, data, endian)
  byte_array_append_uint8 (array, data)
  chunk_array_to_string (chunks)
  common_bytes_align (bytes, blksz, padval)
  common_bytes_compare (bytes1, bytes2)
  common_bytes_compare_raw (buf1, bufsz1, buf2, bufsz2)
  common_bytes_is_empty (bytes)
  common_bytes_pad (bytes, sz)
  common_dump_bytes (log_domain, title, bytes)
  common_dump_full (log_domain, title, data, len, columns, flags)
  common_dump_raw (log_domain, title, data, len)
  common_error_array_get_best (errors)
  common_extract_archive (blob, dir)
  common_find_program_in_path (basename)
  common_firmware_builder (bytes, script_fn, output_fn)
  common_fnmatch (pattern, str)
  common_get_contents_bytes (filename)
  common_get_contents_fd (fd, count)
  common_get_files_recursive (path)
  common_get_path (path_kind)
  common_guid_is_plausible (buf)
  common_kernel_locked_down ()
  common_mkdir_parent (filename)
  common_read_uint16 (buf, endian)
  common_read_uint16_safe (buf, bufsz, offset, endian)
  common_read_uint32 (buf, endian)
  common_read_uint32_safe (buf, bufsz, offset, endian)
  common_read_uint8_safe (buf, bufsz, offset)
  common_realpath (filename)
  common_rmtree (directory)
  common_set_contents_bytes (filename, bytes)
  common_spawn_sync (argv, handler_cb, handler_user_data, timeout_ms, cancellable)
  common_string_append_kb (str, idt, key, value)
  common_string_append_ku (str, idt, key, value)
  common_string_append_kv (str, idt, key, value)
  common_string_append_kx (str, idt, key, value)
  common_string_replace (string, search, replace)
  common_strnsplit (str, sz, delimiter, max_tokens)
  common_strstrip (str)
  common_strtoull (str)
  common_strwidth (text)
  common_vercmp (version_a, version_b)
  common_vercmp_full (version_a, version_b, fmt)
  common_version_ensure_semver (version)
  common_version_from_uint16 (val, kind)
  common_version_from_uint32 (val, kind)
  common_version_from_uint64 (val, kind)
  common_version_guess_format (version)
  common_version_parse (version)
  common_version_parse_from_format (version, fmt)
  common_version_verify_format (version, fmt)
  common_write_uint16 (buf, val_native, endian)
  common_write_uint32 (buf, val_native, endian)
  memcpy_safe (dst, dst_sz, dst_offset, src, src_sz, src_offset, n)

Details

FwupdPlugin.byte_array_append_uint16(array, data, endian)
Parameters:

Adds a 16 bit integer to a byte array

New in version 1.3.1.

FwupdPlugin.byte_array_append_uint32(array, data, endian)
Parameters:

Adds a 32 bit integer to a byte array

New in version 1.3.1.

FwupdPlugin.byte_array_append_uint8(array, data)
Parameters:

Adds a 8 bit integer to a byte array

New in version 1.3.1.

FwupdPlugin.chunk_array_to_string(chunks)
Parameters:chunks ([FwupdPlugin.Chunk]) – array of packets
Returns:A string
Return type:str

Converts all the chunked packets in an array to a string representation.

New in version 1.0.1.

FwupdPlugin.common_bytes_align(bytes, blksz, padval)
Parameters:
Returns:

a GLib.Bytes, possibly bytes

Return type:

GLib.Bytes

Aligns a block of memory to blksize using the padval value; if the block is already aligned then the original bytes is returned.

New in version 1.2.4.

FwupdPlugin.common_bytes_compare(bytes1, bytes2)
Parameters:
Raises:

GLib.Error

Returns:

True if bytes1 and bytes2 are identical

Return type:

bool

Compares the buffers for equality.

New in version 1.2.6.

FwupdPlugin.common_bytes_compare_raw(buf1, bufsz1, buf2, bufsz2)
Parameters:
  • buf1 (int) – a buffer
  • bufsz1 (int) – sizeof buf1
  • buf2 (int) – another buffer
  • bufsz2 (int) – sizeof buf2
Raises:

GLib.Error

Returns:

True if buf1 and buf2 are identical

Return type:

bool

Compares the buffers for equality.

New in version 1.3.2.

FwupdPlugin.common_bytes_is_empty(bytes)
Parameters:bytes (GLib.Bytes) – a GLib.Bytes
Returns:True if bytes is empty
Return type:bool

Checks if a byte array are just empty (0xff) bytes.

New in version 1.2.6.

FwupdPlugin.common_bytes_pad(bytes, sz)
Parameters:
Returns:

a GLib.Bytes

Return type:

GLib.Bytes

Pads a GLib.Bytes to a given sz with 0xff.

New in version 1.3.1.

FwupdPlugin.common_dump_bytes(log_domain, title, bytes)
Parameters:

Dumps a byte buffer to the screen.

New in version 1.2.2.

FwupdPlugin.common_dump_full(log_domain, title, data, len, columns, flags)
Parameters:

Dumps a raw buffer to the screen.

New in version 1.2.4.

FwupdPlugin.common_dump_raw(log_domain, title, data, len)
Parameters:

Dumps a raw buffer to the screen.

New in version 1.2.2.

FwupdPlugin.common_error_array_get_best(errors)
Parameters:errors ([GLib.Error]) – array of errors
Returns:a GLib.Error, never None
Return type:GLib.Error

Finds the ‘best’ error to show the user from a array of errors, creating a completely bespoke error where required.

New in version 1.0.8.

FwupdPlugin.common_extract_archive(blob, dir)
Parameters:
Raises:

GLib.Error

Returns:

True for success

Return type:

bool

Extracts an archive to a directory.

New in version 0.9.7.

FwupdPlugin.common_find_program_in_path(basename)
Parameters:basename (str) – The program to search
Raises:GLib.Error
Returns:a new str, or None for error
Return type:str

Looks for a program in the PATH variable

New in version 1.1.2.

FwupdPlugin.common_firmware_builder(bytes, script_fn, output_fn)
Parameters:
  • bytes (GLib.Bytes) – The data to use
  • script_fn (str) – Name of the script to run in the tarball, e.g. startup.sh
  • output_fn (str) – Name of the generated firmware, e.g. firmware.bin
Raises:

GLib.Error

Returns:

a new GLib.Bytes, or None for error

Return type:

GLib.Bytes

Builds a firmware file using tools from the host session in a bubblewrap jail. Several things happen during build:

The bytes data is untarred to a temporary location

A bubblewrap container is set up

The startup.sh script is run inside the container

The firmware.bin is extracted from the container

The temporary location is deleted

New in version 0.9.7.

FwupdPlugin.common_fnmatch(pattern, str)
Parameters:
  • pattern (str) – a glob pattern, e.g. *foo*
  • str (str) – a string to match against the pattern, e.g. bazfoobar
Returns:

True if the string matched

Return type:

bool

Matches a string against a glob pattern.

New in version 1.3.5.

FwupdPlugin.common_get_contents_bytes(filename)
Parameters:filename (str) – A filename
Raises:GLib.Error
Returns:a GLib.Bytes, or None for failure
Return type:GLib.Bytes

Reads a blob of data from a file.

New in version 0.9.7.

FwupdPlugin.common_get_contents_fd(fd, count)
Parameters:
  • fd (int) – A file descriptor
  • count (int) – The maximum number of bytes to read
Raises:

GLib.Error

Returns:

a GLib.Bytes, or None

Return type:

GLib.Bytes

Reads a blob from a specific file descriptor.

Note: this will close the fd when done

New in version 0.9.5.

FwupdPlugin.common_get_files_recursive(path)
Parameters:path (str) – a directory name
Raises:GLib.Error
Returns:array of files, or None for error
Return type:[str]

Returns every file found under directory, and any subdirectory. If any path under directory cannot be accessed due to permissions an error will be returned.

New in version 1.0.6.

FwupdPlugin.common_get_path(path_kind)
Parameters:path_kind (FwupdPlugin.PathKind) – A FwupdPlugin.PathKind e.g. FwupdPlugin.PathKind.DATADIR_PKG
Returns:a system path, or None if invalid
Return type:str

Gets a fwupd-specific system path. These can be overridden with various environment variables, for instance %FWUPD_DATADIR.

New in version 1.0.8.

FwupdPlugin.common_guid_is_plausible(buf)
Parameters:buf (int) – a buffer of data
Returns:True if it looks like a GUID, False if not
Return type:bool

Checks whether a chunk of memory looks like it could be a GUID.

New in version 1.2.5.

FwupdPlugin.common_kernel_locked_down()
Return type:bool

Determines if kernel lockdown in effect

New in version 1.3.8.

FwupdPlugin.common_mkdir_parent(filename)
Parameters:filename (str) – A full pathname
Raises:GLib.Error
Returns:True for success
Return type:bool

Creates any required directories, including any parent directories.

New in version 0.9.7.

FwupdPlugin.common_read_uint16(buf, endian)
Parameters:
Returns:

a value in host byte-order

Return type:

int

Read a value from a buffer using a specified endian.

New in version 1.0.3.

FwupdPlugin.common_read_uint16_safe(buf, bufsz, offset, endian)
Parameters:
  • buf (int) – source buffer
  • bufsz (int) – maximum size of buf, typically sizeof(buf)
  • offset (int) – offset in bytes into buf to copy from
  • endian (int) – A #FuEndianType, e.g. GLib.LITTLE_ENDIAN
Raises:

GLib.Error

Returns:

True if value was set, False otherwise

value:the parsed value

Return type:

(bool, value: int)

Read a value from a buffer using a specified endian in a safe way.

You don’t need to use this function in “obviously correct” cases, nor should you use it when performance is a concern. Only us it when you’re not sure if malicious data from a device or firmware could cause memory corruption.

New in version 1.3.3.

FwupdPlugin.common_read_uint32(buf, endian)
Parameters:
Returns:

a value in host byte-order

Return type:

int

Read a value from a buffer using a specified endian.

New in version 1.0.3.

FwupdPlugin.common_read_uint32_safe(buf, bufsz, offset, endian)
Parameters:
  • buf (int) – source buffer
  • bufsz (int) – maximum size of buf, typically sizeof(buf)
  • offset (int) – offset in bytes into buf to copy from
  • endian (int) – A #FuEndianType, e.g. GLib.LITTLE_ENDIAN
Raises:

GLib.Error

Returns:

True if value was set, False otherwise

value:the parsed value

Return type:

(bool, value: int)

Read a value from a buffer using a specified endian in a safe way.

You don’t need to use this function in “obviously correct” cases, nor should you use it when performance is a concern. Only us it when you’re not sure if malicious data from a device or firmware could cause memory corruption.

New in version 1.3.3.

FwupdPlugin.common_read_uint8_safe(buf, bufsz, offset)
Parameters:
  • buf (int) – source buffer
  • bufsz (int) – maximum size of buf, typically sizeof(buf)
  • offset (int) – offset in bytes into buf to copy from
Raises:

GLib.Error

Returns:

True if value was set, False otherwise

value:the parsed value

Return type:

(bool, value: int)

Read a value from a buffer in a safe way.

You don’t need to use this function in “obviously correct” cases, nor should you use it when performance is a concern. Only us it when you’re not sure if malicious data from a device or firmware could cause memory corruption.

New in version 1.3.3.

FwupdPlugin.common_realpath(filename)
Parameters:filename (str) – a filename
Raises:GLib.Error
Returns:A filename, or None if invalid or not found
Return type:str

Finds the canonicalized absolute filename for a path.

New in version 1.2.6.

FwupdPlugin.common_rmtree(directory)
Parameters:directory (str) – a directory name
Raises:GLib.Error
Returns:True for success, False otherwise
Return type:bool

Recursively removes a directory.

New in version 0.9.7.

FwupdPlugin.common_set_contents_bytes(filename, bytes)
Parameters:
  • filename (str) – A filename
  • bytes (GLib.Bytes) – The data to write
Raises:

GLib.Error

Returns:

True for success

Return type:

bool

Writes a blob of data to a filename, creating the parent directories as required.

New in version 0.9.5.

FwupdPlugin.common_spawn_sync(argv, handler_cb, handler_user_data, timeout_ms, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True for success

Return type:

bool

Runs a subprocess and waits for it to exit. Any output on standard out or standard error will be forwarded to handler_cb as whole lines.

New in version 0.9.7.

FwupdPlugin.common_string_append_kb(str, idt, key, value)
Parameters:

Appends a key and boolean value to a string

New in version 1.2.4.

FwupdPlugin.common_string_append_ku(str, idt, key, value)
Parameters:

Appends a key and unsigned integer to a string

New in version 1.2.4.

FwupdPlugin.common_string_append_kv(str, idt, key, value)
Parameters:

Appends a key and string value to a string

New in version 1.2.4.

FwupdPlugin.common_string_append_kx(str, idt, key, value)
Parameters:

Appends a key and hex integer to a string

New in version 1.2.4.

FwupdPlugin.common_string_replace(string, search, replace)
Parameters:
  • string (GLib.String) – The GLib.String to operate on
  • search (str) – The text to search for
  • replace (str) – The text to use for substitutions
Returns:

the number of replacements done, or 0 if search is not found.

Return type:

int

Performs multiple search and replace operations on the given string.

New in version 1.2.0.

FwupdPlugin.common_strnsplit(str, sz, delimiter, max_tokens)
Parameters:
  • str (str) – a string to split
  • sz (int) – size of str
  • delimiter (str) – a string which specifies the places at which to split the string
  • max_tokens (int) – the maximum number of pieces to split str into
Returns:

a newly-allocated None-terminated array of strings

Return type:

[str]

Splits a string into a maximum of max_tokens pieces, using the given delimiter. If max_tokens is reached, the remainder of string is appended to the last token.

New in version 1.3.1.

FwupdPlugin.common_strstrip(str)
Parameters:str (str) – A string, e.g. ” test “
Returns:newly allocated string
Return type:str

Removes leading and trailing whitespace from a constant string.

New in version 1.1.2.

FwupdPlugin.common_strtoull(str)
Parameters:str (str) – A string, e.g. “0x1234”
Returns:integer value, or 0x0 for error
Return type:int

Converts a string value to an integer. Values are assumed base 10, unless prefixed with “0x” where they are parsed as base 16.

New in version 1.1.2.

FwupdPlugin.common_strwidth(text)
Parameters:text (str) – The string to operate on
Returns:width of text
Return type:int

Returns the width of the string in displayed characters on the console.

New in version 1.3.2.

FwupdPlugin.common_vercmp(version_a, version_b)
Parameters:
  • version_a (str) – the semver release version, e.g. 1.2.3
  • version_b (str) – the semver release version, e.g. 1.2.3.1
Returns:

-1 if a < b, +1 if a > b, 0 if they are equal, and GObject.G_MAXINT on error

Return type:

int

Compares version numbers for sorting.

New in version 0.3.5.

FwupdPlugin.common_vercmp_full(version_a, version_b, fmt)
Parameters:
Returns:

-1 if a < b, +1 if a > b, 0 if they are equal, and GObject.G_MAXINT on error

Return type:

int

Compares version numbers for sorting taking into account the version format if required.

New in version 1.3.9.

FwupdPlugin.common_version_ensure_semver(version)
Parameters:version (str) – A version number, e.g. `` V1.2.3 ``
Returns:A version number, e.g. “1.2.3”
Return type:str

Builds a semver from the possibly crazy version number.

New in version 1.2.9.

FwupdPlugin.common_version_from_uint16(val, kind)
Parameters:
Returns:

A version number, e.g. “1.3”, or None if not supported

Return type:

str

Returns a dotted decimal version string from a 16 bit number.

New in version 1.2.0.

FwupdPlugin.common_version_from_uint32(val, kind)
Parameters:
Returns:

A version number, e.g. “1.0.3”, or None if not supported

Return type:

str

Returns a dotted decimal version string from a 32 bit number.

New in version 1.2.0.

FwupdPlugin.common_version_from_uint64(val, kind)
Parameters:
Returns:

A version number, e.g. “1.2.3.4”, or None if not supported

Return type:

str

Returns a dotted decimal version string from a 64 bit number.

New in version 1.3.6.

FwupdPlugin.common_version_guess_format(version)
Parameters:version (str) – A version number, e.g. “1.2.3”
Returns:A Fwupd.VersionFormat, e.g. Fwupd.VersionFormat.QUAD
Return type:Fwupd.VersionFormat

Guesses the version format from the version number. This is only a heuristic and plugins and components should explicitly set the version format whenever possible.

If the version format cannot be guessed with any degree of accuracy, the Fwupd.VersionFormat.UNKNOWN constant is returned.

New in version 1.2.0.

FwupdPlugin.common_version_parse(version)
Parameters:version (str) – A version number
Returns:A version number, e.g. “1.0.3”
Return type:str

Returns a dotted decimal version string from a version string. The supported formats are:

  • Dotted decimal, e.g. “1.2.3”
  • Base 16, a hex number *with* a 0x prefix, e.g. “0x10203”
  • Base 10, a string containing just [0-9], e.g. “66051”
  • Date in YYYYMMDD format, e.g. 20150915

Anything with a ‘.’ or that doesn’t match [0-9] or 0x[a-f,0-9] is considered a string and returned without modification.

New in version 1.2.0.

FwupdPlugin.common_version_parse_from_format(version, fmt)
Parameters:
Returns:

A version number, e.g. “1.0.3”

Return type:

str

Returns a dotted decimal version string from a version string using fmt. The supported formats are:

  • Dotted decimal, e.g. “1.2.3”
  • Base 16, a hex number *with* a 0x prefix, e.g. “0x10203”
  • Base 10, a string containing just [0-9], e.g. “66051”
  • Date in YYYYMMDD format, e.g. 20150915

Anything with a ‘.’ or that doesn’t match [0-9] or 0x[a-f,0-9] is considered a string and returned without modification.

New in version 1.3.3.

FwupdPlugin.common_version_verify_format(version, fmt)
Parameters:
Raises:

GLib.Error

Returns:

True or False

Return type:

bool

Verifies if a version matches the input format.

New in version 1.2.9.

FwupdPlugin.common_write_uint16(buf, val_native, endian)
Parameters:
  • buf (int) – A writable buffer
  • val_native (int) – a value in host byte-order
  • endian (int) – A #FuEndianType, e.g. GLib.LITTLE_ENDIAN

Writes a value to a buffer using a specified endian.

New in version 1.0.3.

FwupdPlugin.common_write_uint32(buf, val_native, endian)
Parameters:
  • buf (int) – A writable buffer
  • val_native (int) – a value in host byte-order
  • endian (int) – A #FuEndianType, e.g. GLib.LITTLE_ENDIAN

Writes a value to a buffer using a specified endian.

New in version 1.0.3.

FwupdPlugin.memcpy_safe(dst, dst_sz, dst_offset, src, src_sz, src_offset, n)
Parameters:
  • dst (int) – destination buffer
  • dst_sz (int) – maximum size of dst, typically sizeof(dst)
  • dst_offset (int) – offset in bytes into dst to copy to
  • src (int) – source buffer
  • src_sz (int) – maximum size of dst, typically sizeof(src)
  • src_offset (int) – offset in bytes into src to copy from
  • n (int) – number of bytes to copy from src+`offset` from
Raises:

GLib.Error

Returns:

True if the bytes were copied, False otherwise

Return type:

bool

Copies some memory using memcpy in a safe way. Providing the buffer sizes of both the destination and the source allows us to check for buffer overflow.

Providing the buffer offsets also allows us to check reading past the end of the source buffer. For this reason the caller should NEVER add an offset to src or dst.

You don’t need to use this function in “obviously correct” cases, nor should you use it when performance is a concern. Only us it when you’re not sure if malicious data from a device or firmware could cause memory corruption.

New in version 1.3.1.