Functions ¶

Checks whether optname is a valid option name for an offload feature.

New in version 1.20.

NM.ethtool_optname_is_pause(optname)¶

Parameters:: optname (str or None) – the option name to check
Returns:: True, if optname is valid
Return type:: bool

Checks whether optname is a valid option name for a pause setting.

New in version 1.32.

NM.ethtool_optname_is_ring(optname)¶

Parameters:: optname (str or None) – the option name to check
Returns:: True, if optname is valid
Return type:: bool

Checks whether optname is a valid option name for a ring setting.

New in version 1.26.

NM.ip_route_attribute_validate(name, value, family)¶

Parameters:

name (str) – the attribute name
value (GLib.Variant) – the attribute value
family (int) – IP address family of the route

Raises:

Returns:

True if the attribute is valid, False otherwise

known:: on return, whether the attribute name is a known one

Return type:

(bool, known: bool)

Validates a route attribute, i.e. checks that the attribute is a known one and the value is of the correct type and well-formed.

New in version 1.8.

NM.ip_route_get_variant_attribute_spec()¶

Returns:: the specifiers for route attributes
Return type:: NM.VariantAttributeSpec

New in version 1.8.

NM.ip_routing_rule_from_string(str, to_string_flags, extra_args)¶

Parameters:

str (str) – the string representation to convert to an NM.IPRoutingRule
to_string_flags (NM.IPRoutingRuleAsStringFlags) – NM.IPRoutingRuleAsStringFlags for controlling the string conversion.
extra_args ({object: object} or None) – extra arguments for controlling the string conversion. Currently, not extra arguments are supported.

Raises:

Returns:

the new NM.IPRoutingRule or None on error.

Return type:

NM.IPRoutingRule

New in version 1.18.

NM.keyfile_read(keyfile, base_dir, handler_flags, handler, *user_data)¶

Parameters:

keyfile (GLib.KeyFile) – the keyfile from which to create the connection
base_dir (str) – when reading certificates from files with relative name, the relative path is made absolute using base_dir. This must be an absolute path.
handler_flags (NM.KeyfileHandlerFlags) – the NM.KeyfileHandlerFlags.
handler (NM.KeyfileReadHandler or None) – read handler
user_data (object or None) – user data for read handler

Raises:

Returns:

on success, returns the created connection.

Return type:

NM.Connection

Tries to create a NM.Connection from a keyfile. The resulting keyfile is not normalized and might not even verify.

New in version 1.30.

NM.keyfile_write(connection, handler_flags, handler, *user_data)¶

Parameters:

connection (NM.Connection) – the NM.Connection to persist to keyfile.
handler_flags (NM.KeyfileHandlerFlags) – the NM.KeyfileHandlerFlags.
handler (NM.KeyfileWriteHandler or None) – optional handler for events and to override the default behavior.
user_data (object or None) – argument for handler.

Raises:

Returns:

a new GLib.KeyFile or None on error.

Return type:

GLib.KeyFile

connection should verify as a valid profile according to NM.Connection.verify(). If it does not verify, the keyfile may be incomplete and the parser may not be able to fully recreate the original profile.

New in version 1.30.

NM.manager_error_quark()¶

Return type:: int

NM.range_from_str(str)¶

Parameters:: str (str) – the string representation of a range
Raises:: GLib.Error
Returns:: the NM.Range or None
Return type:: NM.Range

Parses the string representation of the range to create a NM.Range instance.

New in version 1.42.

NM.secret_agent_error_quark()¶

Return type:: int

NM.settings_error_quark()¶

Return type:: int

NM.sriov_vf_attribute_validate(name, value)¶

Parameters:

name (str) – the attribute name
value (GLib.Variant) – the attribute value

Raises:

Returns:

True if the attribute is valid, False otherwise

known:: on return, whether the attribute name is a known one

Return type:

(bool, known: bool)

Validates a VF attribute, i.e. checks that the attribute is a known one, the value is of the correct type and well-formed.

New in version 1.42.

NM.utils_ap_mode_security_valid(type, wifi_caps)¶

Parameters:

type (NM.UtilsSecurityType) – the security type to check device capabilities against, e.g. NM.UtilsSecurityType.STATIC_WEP
wifi_caps (NM.DeviceWifiCapabilities) – bitfield of the capabilities of the specific Wi-Fi device, e.g. NM.DeviceWifiCapabilities.CIPHER_WEP40

Returns:

True if the device capabilities are compatible with the desired type, False if they are not.

Return type:

Given a set of device capabilities, and a desired security type to check against, determines whether the combination of device capabilities and desired security type are valid for AP/Hotspot connections.

NM.utils_base64secret_decode(base64_key, required_key_len)¶

Parameters:

base64_key (str) – the (possibly invalid) base64 encode key.
required_key_len (int) – the expected (binary) length of the key after decoding. If the length does not match, the validation fails.

Returns:

True if the input key is a valid base64 encoded key with required_key_len bytes.

out_key:: an optional output buffer for the binary key. If given, it will be filled with exactly required_key_len bytes.

Return type:

(bool, out_key: int)

New in version 1.16.

NM.utils_bin2hexstr(src, final_len)¶

Parameters:

src (bytes) – an array of bytes
final_len (int) – an index where to cut off the returned string, or -1

Returns:

the textual form of bytes

Return type:

Converts the byte array src into a hexadecimal string. If final_len is greater than -1, the returned string is terminated at that index (returned_string[final_len] == ‘\0’),

NM.utils_bond_mode_int_to_string(mode)¶

Parameters:: mode (int) – bonding mode as a numeric value
Returns:: bonding mode string, or None on error
Return type:: str

Convert bonding mode from integer value to descriptive name. See https://www.kernel.org/doc/Documentation/networking/bonding.txt for available modes.

New in version 1.2.

NM.utils_bond_mode_string_to_int(mode)¶

Parameters:: mode (str) – bonding mode as string
Returns:: numeric bond mode, or -1 on error
Return type:: int

Convert bonding mode from string representation to numeric value. See https://www.kernel.org/doc/Documentation/networking/bonding.txt for available modes. The mode string can be either a descriptive name or a number (as string).

New in version 1.2.

NM.utils_check_virtual_device_compatibility(virtual_type, other_type)¶

Parameters:

virtual_type (GObject.GType) – a virtual connection type
other_type (GObject.GType) – a connection type to test against virtual_type

Returns:

True or False

Return type:

Determines if a connection of type virtual_type can (in the general case) work with connections of type other_type.

If virtual_type is %NM_TYPE_SETTING_VLAN, then this checks if other_type is a valid type for the parent of a VLAN.

If virtual_type is a “master” type (eg, %NM_TYPE_SETTING_BRIDGE), then this checks if other_type is a valid type for a slave of that master.

Note that even if this returns True it is not guaranteed that every connection of type other_type is compatible with virtual_type; it may depend on the exact configuration of the two connections, or on the capabilities of an underlying device driver.

NM.utils_ensure_gtypes()¶

This ensures that all NM.Setting GTypes are created. For example, after this call, GObject.type_from_name(”NM.SettingConnection") will work.

This cannot fail and does nothing if the type already exists.

New in version 1.42.

NM.utils_enum_from_str(type, str)¶

Parameters:

type (GObject.GType) – the GObject.GType of the enum
str (str) – the input string

Returns:

True if the conversion was successful, False otherwise

out_value:: the output value
err_token:: location to store the first unrecognized token

Return type:

(bool, out_value: int, err_token: str or None)

Converts a string to the matching enum value.

If the enum is a GObject.TYPE_FLAGS the function returns the logical OR of values matching the comma-separated tokens in the string; if an unknown token is found the function returns False and stores a pointer to a newly allocated string containing the unrecognized token in err_token.

New in version 1.2.

NM.utils_enum_get_values(type, from_, to)¶

Parameters:

type (GObject.GType) – the GObject.GType of the enum
from (int) – the first element to be returned
to (int) – the last element to be returned

Returns:

a None-terminated dynamically-allocated array of static strings or None on error

Return type:

[str]

Returns the list of possible values for a given enum.

New in version 1.2.

NM.utils_enum_to_str(type, value)¶

Parameters:

type (GObject.GType) – the GObject.GType of the enum
value (int) – the value to be translated

Returns:

a newly allocated string or None

Return type:

Converts an enum value to its string representation. If the enum is a GObject.TYPE_FLAGS the function returns a comma-separated list of matching values. If the value has no corresponding string representation, it is converted to a number. For enums it is converted to a decimal number, for flags to an (unsigned) hex number.

New in version 1.2.

NM.utils_escape_ssid(ssid)¶

Parameters:: ssid (bytes) – pointer to a buffer containing the SSID data
Returns:: pointer to the escaped SSID, which uses an internal static buffer and will be overwritten by subsequent calls to this function
Return type:: str

This function does a quick printable character conversion of the SSID, simply replacing embedded NULLs and non-printable characters with the hexadecimal representation of that character. Intended for debugging only, should not be used for display of SSIDs.

Warning: this function uses a static buffer. It is not thread-safe. Don’t use this function.

Deprecated since version 1.46: use NM.utils_ssid_to_utf8() or NM.utils_bin2hexstr().

NM.utils_file_is_certificate(filename)¶

Parameters:: filename (str) – name of the file to test
Returns:: True if the file is a certificate, False if it is not
Return type:: bool

Tests if filename has a valid extension for an X.509 certificate file (“.cer”, “.crt”, “.der”, or “.pem”), and contains a certificate in a format recognized by NetworkManager.

NM.utils_file_is_pkcs12(filename)¶

Parameters:: filename (str) – name of the file to test
Returns:: True if the file is PKCS# 12, False if it is not
Return type:: bool

Tests if filename is a PKCS# 12 file.

NM.utils_file_is_private_key(filename)¶

Parameters:

filename (str) – name of the file to test

Returns:

True if the file is a private key, False if it is not

out_encrypted:: on return, whether the file is encrypted

Return type:

(bool, out_encrypted: bool)

Tests if filename has a valid extension for an X.509 private key file (“.der”, “.key”, “.pem”, or “.p12”), and contains a private key in a format recognized by NetworkManager.

NM.utils_file_search_in_paths(progname, try_first, paths, file_test_flags, predicate, *user_data)¶

Parameters:

progname (str) – the helper program name, like “iptables” Must be a non-empty string, without path separator (/).
try_first (str or None) – a custom path to try first before searching. It is silently ignored if it is empty or not an absolute path.
paths (str or None) – a None terminated list of search paths. Can be empty or None, in which case only try_first is checked.
file_test_flags (GLib.FileTest) – the flags passed to GLib.file_test() when searching for progname. Set it to 0 to skip the GLib.file_test().
predicate (NM.UtilsFileSearchInPathsPredicate) – if given, pass the file name to this function for additional checks. This check is performed after the check for file_test_flags. You cannot omit both file_test_flags and predicate.
user_data (object or None) – user data for predicate function.

Raises:

Returns:

the full path to the helper, if found, or None if not found. The returned string is not owned by the caller, but later invocations of the function might overwrite it.

Return type:

Searches for a progname file in a list of search paths.

NM.utils_format_variant_attributes(attributes, attr_separator, key_value_separator)¶

Parameters:

attributes ({str: GLib.Variant}) – a GLib.HashTable mapping attribute names to GLib.Variant values
attr_separator (int) – the attribute separator character
key_value_separator (int) – character separating key and values

Returns:

the string representing attributes, or None in case there are no attributes

Return type:

Format attributes to a string.

New in version 1.8.

NM.utils_get_timestamp_msec()¶

Returns:: time in milliseconds
Return type:: int

Gets current time in milliseconds of CLOCK_BOOTTIME.

New in version 1.12.

NM.utils_hexstr2bin(hex)¶

Parameters:: hex (str) – a string of hexadecimal characters with optional ‘:’ separators
Returns:: the converted bytes, or None on error
Return type:: GLib.Bytes

Converts a hexadecimal string hex into an array of bytes. The optional separator ‘:’ may be used between single or pairs of hexadecimal characters, eg “00:11” or “0:1”. Any “0x” at the beginning of hex is ignored. hex may not start or end with ‘:’.

NM.utils_hwaddr_atoba(asc, length)¶

Parameters:

asc (str) – the ASCII representation of a hardware address
length (int) – the expected length in bytes of the result

Returns:

a new GLib.ByteArray, or None if asc couldn’t be parsed

Return type:

bytes

Parses asc and converts it to binary form in a GLib.ByteArray. See NM.utils_hwaddr_aton() if you don’t want a GLib.ByteArray.

NM.utils_hwaddr_aton(asc, buffer)¶

Parameters:

asc (str) – the ASCII representation of a hardware address
buffer (bytes) – buffer to store the result into

Returns:

buffer, or None if asc couldn’t be parsed or would be shorter or longer than length.

Return type:

int

Parses asc and converts it to binary form in buffer. Bytes in asc can be separated by colons (:), or hyphens (-), but not mixed.

NM.utils_hwaddr_canonical(asc, length)¶

Parameters:

asc (str) – the ASCII representation of a hardware address
length (int) – the length of address that asc is expected to convert to (or -1 to accept any length up to NM.UTILS_HWADDR_LEN_MAX)

Returns:

the canonicalized address if asc appears to be a valid hardware address of the indicated length, None if not.

Return type:

Parses asc to see if it is a valid hardware address of the given length, and if so, returns it in canonical form (uppercase, with leading 0s as needed, and with colons rather than hyphens).

NM.utils_hwaddr_len(type)¶

Parameters:: type (int) – the type of address; either ARPHRD_ETHER or ARPHRD_INFINIBAND
Returns:: the length or zero if the type is unrecognized.
Return type:: int

Returns the length in octets of a hardware address of type type.

Before 1.28, it was an error to call this function with any value other than ARPHRD_ETHER or ARPHRD_INFINIBAND.

NM.utils_hwaddr_matches(hwaddr1, hwaddr1_len, hwaddr2, hwaddr2_len)¶

Parameters:

hwaddr1 (object or None) – pointer to a binary or ASCII hardware address, or None
hwaddr1_len (int) – size of hwaddr1, or -1 if hwaddr1 is ASCII
hwaddr2 (object or None) – pointer to a binary or ASCII hardware address, or None
hwaddr2_len (int) – size of hwaddr2, or -1 if hwaddr2 is ASCII

Returns:

True if hwaddr1 and hwaddr2 are equivalent, False if they are different (or either of them is invalid).

Return type:

Generalized hardware address comparison function. Tests if hwaddr1 and hwaddr2 “equal” (or more precisely, “equivalent”), with several advantages over a simple memcmp():

If hwaddr1_len or hwaddr2_len is -1, then the corresponding address is assumed to be ASCII rather than binary, and will be converted to binary before being compared.

If hwaddr1 or hwaddr2 is None, it is treated instead as though it was a zero-filled buffer hwaddr1_len or hwaddr2_len bytes long.

If hwaddr1 and hwaddr2 are InfiniBand hardware addresses (that is, if they are INFINIBAND_ALEN bytes long in binary form) then only the last 8 bytes are compared, since those are the only bytes that actually identify the hardware. (The other 12 bytes will change depending on the configuration of the InfiniBand fabric that the device is connected to.)

If a passed-in ASCII hardware address cannot be parsed, or would parse to an address larger than NM.UTILS_HWADDR_LEN_MAX, then it will silently fail to match. (This means that externally-provided address strings do not need to be sanity-checked before comparing them against known good addresses; they are guaranteed to not match if they are invalid.)

NM.utils_hwaddr_ntoa(addr)¶

Parameters:: addr (bytes) – a binary hardware address
Returns:: the textual form of addr
Return type:: str

Converts addr to textual form.

NM.utils_hwaddr_valid(asc, length)¶

Parameters:

asc (str) – the ASCII representation of a hardware address
length (int) – the length of address that asc is expected to convert to (or -1 to accept any length up to NM.UTILS_HWADDR_LEN_MAX)

Returns:

True if asc appears to be a valid hardware address of the indicated length, False if not.

Return type:

Parses asc to see if it is a valid hardware address of the given length.

NM.utils_iface_valid_name(name)¶

Parameters:

name (str or None) – Name of interface

Returns:

True if interface name is valid, otherwise False is returned.

Before 1.20, this function did not accept None as name argument. If you want to run against older versions of libnm, don’t pass None.

Return type:

Validate the network interface name.

Deprecated since version 1.6: Use NM.utils_is_valid_iface_name() instead, with better error reporting.

NM.utils_ip4_addresses_from_variant(value)¶

Parameters:

value (GLib.Variant) – a GLib.Variant of type ‘aau’

Returns:

a newly allocated GLib.PtrArray of NM.IPAddress objects

out_gateway:: on return, will contain the IP gateway

Return type:

([NM.IPAddress], out_gateway: str or None)

Utility function to convert a GLib.Variant of type ‘aau’ representing a list of NetworkManager IPv4 addresses (which are tuples of address, prefix, and gateway) into a GLib.PtrArray of NM.IPAddress objects. The “gateway” field of the first address (if set) will be returned in out_gateway; the “gateway” fields of the other addresses are ignored. Note that invalid addresses are discarded but the valid addresses are still returned.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

NM.utils_ip4_addresses_to_variant(addresses, gateway)¶

Parameters:

addresses ([NM.IPAddress]) – an array of NM.IPAddress objects
gateway (str or None) – the gateway IP address

Returns:

a new floating GLib.Variant representing addresses.

Return type:

GLib.Variant

Utility function to convert a GLib.PtrArray of NM.IPAddress objects representing IPv4 addresses into a GLib.Variant of type ‘aau’ representing an array of NetworkManager IPv4 addresses (which are tuples of address, prefix, and gateway). The “gateway” field of the first address will get the value of gateway (if non-None). In all of the other addresses, that field will be 0.

NM.utils_ip4_dns_from_variant(value)¶

Parameters:: value (GLib.Variant) – a GLib.Variant of type ‘au’
Returns:: a None-terminated array of IP address strings.
Return type:: str

Utility function to convert a GLib.Variant of type ‘au’ representing a list of IPv4 addresses into an array of IP address strings.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

NM.utils_ip4_dns_to_variant(dns)¶

Parameters:: dns (str) – an array of IP address strings
Returns:: a new floating GLib.Variant representing dns.
Return type:: GLib.Variant

Utility function to convert an array of IP address strings int a GLib.Variant of type ‘au’ representing an array of IPv4 addresses.

NM.utils_ip4_get_default_prefix(ip)¶

Parameters:: ip (int) – an IPv4 address (in network byte order)
Returns:: the default class prefix for the given IP
Return type:: int

When the Internet was originally set up, various ranges of IP addresses were segmented into three network classes: A, B, and C. This function will return a prefix that is associated with the IP address specified defining where it falls in the predefined classes.

NM.utils_ip4_netmask_to_prefix(netmask)¶

Parameters:: netmask (int) – an IPv4 netmask in network byte order. Usually the netmask has all leading bits up to the prefix set so that the netmask is identical to having the first prefix bits of the address set. If that is not the case and there are “holes” in the mask, the prefix is determined based on the lowest bit set.
Returns:: the CIDR prefix represented by the netmask
Return type:: int

NM.utils_ip4_prefix_to_netmask(prefix)¶

Parameters:: prefix (int) – a CIDR prefix, must be not larger than 32.
Returns:: the netmask represented by the prefix, in network byte order
Return type:: int

NM.utils_ip4_routes_from_variant(value)¶

Parameters:: value (GLib.Variant) – GLib.Variant of type ‘aau’
Returns:: a newly allocated GLib.PtrArray of NM.IPRoute objects
Return type:: [NM.IPRoute]

Utility function to convert a GLib.Variant of type ‘aau’ representing an array of NetworkManager IPv4 routes (which are tuples of route, prefix, next hop, and metric) into a GLib.PtrArray of NM.IPRoute objects. Note that invalid routes are discarded but the valid routes are still returned.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

NM.utils_ip4_routes_to_variant(routes)¶

Parameters:: routes ([NM.IPRoute]) – an array of #NMIP4Route objects
Returns:: a new floating GLib.Variant representing routes.
Return type:: GLib.Variant

Utility function to convert a GLib.PtrArray of NM.IPRoute objects representing IPv4 routes into a GLib.Variant of type ‘aau’ representing an array of NetworkManager IPv4 routes (which are tuples of route, prefix, next hop, and metric).

NM.utils_ip6_addresses_from_variant(value)¶

Parameters:

value (GLib.Variant) – a GLib.Variant of type ‘a(ayuay)’

Returns:

a newly allocated GLib.PtrArray of NM.IPAddress objects

out_gateway:: on return, will contain the IP gateway

Return type:

([NM.IPAddress], out_gateway: str or None)

Utility function to convert a GLib.Variant of type ‘a(ayuay)’ representing a list of NetworkManager IPv6 addresses (which are tuples of address, prefix, and gateway) into a GLib.PtrArray of NM.IPAddress objects. The “gateway” field of the first address (if set) will be returned in out_gateway; the “gateway” fields of the other addresses are ignored. Note that invalid addresses are discarded but the valid addresses are still returned.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

NM.utils_ip6_addresses_to_variant(addresses, gateway)¶

Parameters:

addresses ([NM.IPAddress]) – an array of NM.IPAddress objects
gateway (str or None) – the gateway IP address

Returns:

a new floating GLib.Variant representing addresses.

Return type:

GLib.Variant

Utility function to convert a GLib.PtrArray of NM.IPAddress objects representing IPv6 addresses into a GLib.Variant of type ‘a(ayuay)’ representing an array of NetworkManager IPv6 addresses (which are tuples of address, prefix, and gateway). The “gateway” field of the first address will get the value of gateway (if non-None). In all of the other addresses, that field will be all 0s.

NM.utils_ip6_dns_from_variant(value)¶

Parameters:: value (GLib.Variant) – a GLib.Variant of type ‘aay’
Returns:: a None-terminated array of IP address strings.
Return type:: str

Utility function to convert a GLib.Variant of type ‘aay’ representing a list of IPv6 addresses into an array of IP address strings. Each “ay” entry must be a IPv6 address in binary form (16 bytes long). Invalid entries are silently ignored.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

NM.utils_ip6_dns_to_variant(dns)¶

Parameters:: dns (str) – an array of IP address strings
Returns:: a new floating GLib.Variant representing dns.
Return type:: GLib.Variant

Utility function to convert an array of IP address strings int a GLib.Variant of type ‘aay’ representing an array of IPv6 addresses.

If a string cannot be parsed, it will be silently ignored.

NM.utils_ip6_routes_from_variant(value)¶

Parameters:: value (GLib.Variant) – GLib.Variant of type ‘a(ayuayu)’
Returns:: a newly allocated GLib.PtrArray of NM.IPRoute objects
Return type:: [NM.IPRoute]

Utility function to convert a GLib.Variant of type ‘a(ayuayu)’ representing an array of NetworkManager IPv6 routes (which are tuples of route, prefix, next hop, and metric) into a GLib.PtrArray of NM.IPRoute objects. Note that invalid routes are ignored but the valid ones are still returned.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

NM.utils_ip6_routes_to_variant(routes)¶

Parameters:: routes ([NM.IPRoute]) – an array of NM.IPRoute objects
Returns:: a new floating GLib.Variant representing routes.
Return type:: GLib.Variant

Utility function to convert a GLib.PtrArray of NM.IPRoute objects representing IPv6 routes into a GLib.Variant of type ‘a(ayuayu)’ representing an array of NetworkManager IPv6 routes (which are tuples of route, prefix, next hop, and metric).

NM.utils_ip_addresses_from_variant(value, family)¶

Parameters:

value (GLib.Variant) – a GLib.Variant of type ‘aa{sv}’
family (int) – an IP address family

Returns:

a newly allocated GLib.PtrArray of NM.IPAddress objects

Return type:

[NM.IPAddress]

Utility function to convert a GLib.Variant representing a list of new-style NetworkManager IPv4 or IPv6 addresses (as described in the documentation for NM.utils_ip_addresses_to_variant()) into a GLib.PtrArray of NM.IPAddress objects. Note that invalid addresses are discarded but the valid addresses are still returned.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

New in version 1.42.

NM.utils_ip_addresses_to_variant(addresses)¶

Parameters:: addresses ([NM.IPAddress]) – an array of NM.IPAddress objects
Returns:: a new floating GLib.Variant representing addresses.
Return type:: GLib.Variant

Utility function to convert a GLib.PtrArray of NM.IPAddress objects representing IPv4 or IPv6 addresses into a GLib.Variant of type ‘aa{sv}’ representing an array of new-style NetworkManager IP addresses. All addresses will include “address” (an IP address string), and “prefix” (a uint). Some addresses may include additional attributes.

New in version 1.42.

NM.utils_ip_routes_from_variant(value, family)¶

Parameters:

value (GLib.Variant) – a GLib.Variant of type ‘aa{sv}’
family (int) – an IP address family

Returns:

a newly allocated GLib.PtrArray of NM.IPRoute objects

Return type:

[NM.IPRoute]

Utility function to convert a GLib.Variant representing a list of new-style NetworkManager IPv4 or IPv6 addresses (as described in the documentation for NM.utils_ip_routes_to_variant()) into a GLib.PtrArray of NM.IPRoute objects. Invalid routes are discarded but the valid routes are still returned.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

New in version 1.42.

NM.utils_ip_routes_to_variant(routes)¶

Parameters:: routes ([NM.IPRoute]) – an array of NM.IPRoute objects
Returns:: a new floating GLib.Variant representing routes.
Return type:: GLib.Variant

Utility function to convert a GLib.PtrArray of NM.IPRoute objects representing IPv4 or IPv6 routes into a GLib.Variant of type ‘aa{sv}’ representing an array of new-style NetworkManager IP routes. All routes will include “dest” (an IP address string), “prefix” (an uint) and optionally “next-hop” (an IP address string) and “metric” (an uint). Some routes may include additional attributes. Note that invalid routes are discarded and only a warning is emitted, but the valid routes are still returned.

New in version 1.42.

NM.utils_ipaddr_valid(family, ip)¶

Parameters:

family (int) – AF_INET or AF_INET6, or AF_UNSPEC to accept either
ip (str) – an IP address

Returns:

True or False

Return type:

Checks if ip contains a valid IP address of the given family.

NM.utils_is_empty_ssid(ssid)¶

Parameters:: ssid (bytes) – pointer to a buffer containing the SSID data
Returns:: True if the SSID is “empty”, False if it is not
Return type:: bool

Different manufacturers use different mechanisms for not broadcasting the AP’s SSID. This function attempts to detect blank/empty SSIDs using a number of known SSID-cloaking methods.

NM.utils_is_json_object(str)¶

Parameters:: str (str) – the JSON string to test
Raises:: GLib.Error
Returns:: whether the passed string is valid JSON. If libnm is not compiled with libjansson support, this check will also return True for possibly invalid inputs. If that is a problem for you, you must validate the JSON yourself.
Return type:: bool

New in version 1.6.

NM.utils_is_uuid(str)¶

Parameters:

str (str or None) – a string that might be a UUID

Returns:

True if str is a UUID, False if not

In older versions, NM.utils_is_uuid() did not accept None as str argument. Don’t pass None if you run against older versions of libnm.

Return type:

Checks if str is a UUID

Deprecated since version 1.32: older versions of NetworkManager had a wrong understanding of what makes a valid UUID. This function can thus accept some inputs as valid, which in fact are not valid UUIDs.

NM.utils_is_valid_iface_name(name)¶

Parameters:

name (str or None) – Name of interface

Raises:

Returns:

True if interface name is valid, otherwise False is returned.

Before 1.20, this function did not accept None as name argument. If you want to run against older versions of libnm, don’t pass None.

Return type:

Validate the network interface name.

This function is a 1:1 copy of the kernel’s interface validation function in net/core/dev.c.

New in version 1.6.

NM.utils_parse_variant_attributes(string, attr_separator, key_value_separator, ignore_unknown, spec)¶

Parameters:

string (str) – the input string
attr_separator (int) – the attribute separator character
key_value_separator (int) – character separating key and values
ignore_unknown (bool) – whether unknown attributes should be ignored
spec (NM.VariantAttributeSpec) – the attribute format specifiers

Raises:

Returns:

a GLib.HashTable mapping attribute names to GLib.Variant values. Warning: the variant are still floating references, owned by the hash table. If you take a reference, ensure to sink the one of the hash table first.

Return type:

{str: GLib.Variant}

Parse attributes from a string.

New in version 1.8.

NM.utils_print(output_mode, msg)¶

Parameters:

output_mode (int) – if 1 it uses g_print(). If 2, it uses g_printerr(). If 0, it uses the same output as internal libnm debug logging does. That is, depending on LIBNM_CLIENT_DEBUG’s “stdout” flag it uses g_print() or g_printerr() and if LIBNM_CLIENT_DEBUG_FILE is set, it writes the output to file instead
msg (str) – the message to print. The function does not append a trailing newline.

The only purpose of this function is to give access to g_print() or g_printerr() from pygobject. libnm can do debug logging by setting LIBNM_CLIENT_DEBUG and uses thereby g_printerr() or g_print(). A plain “print()” function in python is not in sync with these functions (it implements additional buffering). By using NM.utils_print(), the same logging mechanisms can be used.

LIBNM_CLIENT_DEBUG is a list of keywords separated by commas. The keyword “trace” enables printing messages of the lowest up to the highest severity. Likewise, the severities “debug”, “warn” (“warning”) and “error” are honored in similar way. Setting the flags “ERROR” or “WARN” (“WARNING”) implies that respective levels are enabled, but also are ERROR messages printed with g_critical() and WARN messages with g_warning(). Together with G_DEBUG=”fatal-warnings” or G_DEBUG=”fatal-critical” this can be used to abort the program on errors. Note that all <error> messages imply an unexpected data on the D-Bus API (due to a bug). <warn> also implies unexepected data, but that can happen when using different versions of libnm and daemon. For testing, it is good to turn these into assertions.

By default, messages are printed to stderr, unless LIBNM_CLIENT_DEBUG contains “stdout” flag. Also, libnm honors LIBNM_CLIENT_DEBUG_FILE environment. If this is set to a filename pattern (accepting “%%p” for the process ID), then the debug log is written to that file instead of stderr/stdout. With output_mode zero, the same location will be written.

LIBNM_CLIENT_DEBUG_FILE is supported since 1.44. “ERROR”, “WARN” and “WARNING” are supported since 1.46.

New in version 1.30.

NM.utils_same_ssid(ssid1, ssid2, ignore_trailing_null)¶

Parameters:

ssid1 (bytes) – the first SSID to compare
ssid2 (bytes) – the second SSID to compare
ignore_trailing_null (bool) – True to ignore one trailing None byte

Returns:

True if the SSIDs are the same, False if they are not

Return type:

Earlier versions of the Linux kernel added a None byte to the end of the SSID to enable easy printing of the SSID on the console or in a terminal, but this behavior was problematic (SSIDs are simply byte arrays, not strings) and thus was changed. This function compensates for that behavior at the cost of some compatibility with odd SSIDs that may legitimately have trailing NULLs, even though that is functionally pointless.

NM.utils_security_valid(type, wifi_caps, have_ap, adhoc, ap_flags, ap_wpa, ap_rsn)¶

Parameters:

type (NM.UtilsSecurityType) – the security type to check AP flags and device capabilities against, e.g. NM.UtilsSecurityType.STATIC_WEP
wifi_caps (NM.DeviceWifiCapabilities) – bitfield of the capabilities of the specific Wi-Fi device, e.g. NM.DeviceWifiCapabilities.CIPHER_WEP40
have_ap (bool) – whether the ap_flags, ap_wpa, and ap_rsn arguments are valid
adhoc (bool) – whether the capabilities being tested are from an Ad-Hoc AP (IBSS)
ap_flags (NM.80211ApFlags) – bitfield of AP capabilities, e.g. NM._80211ApFlags.PRIVACY
ap_wpa (NM.80211ApSecurityFlags) – bitfield of AP capabilities derived from the AP’s WPA beacon, e.g. (NM._80211ApSecurityFlags.PAIR_TKIP | NM._80211ApSecurityFlags.KEY_MGMT_PSK)
ap_rsn (NM.80211ApSecurityFlags) – bitfield of AP capabilities derived from the AP’s RSN/WPA2 beacon, e.g. (NM._80211ApSecurityFlags.PAIR_CCMP | NM._80211ApSecurityFlags.PAIR_TKIP)

Returns:

True if the device capabilities and AP capabilities intersect and are compatible with the desired type, False if they are not

Return type:

Given a set of device capabilities, and a desired security type to check against, determines whether the combination of device, desired security type, and AP capabilities intersect.

NOTE: this function cannot handle checking security for AP/Hotspot mode; use NM.utils_ap_mode_security_valid() instead.

NM.utils_sriov_vf_from_str(str)¶

Parameters:: str (str) – the input string
Raises:: GLib.Error
Returns:: the virtual function object
Return type:: NM.SriovVF

Converts a string to a SR-IOV virtual function object.

New in version 1.14.

NM.utils_sriov_vf_to_str(vf, omit_index)¶

Parameters:

vf (NM.SriovVF) – the NM.SriovVF
omit_index (bool) – if True, the VF index will be omitted from output string

Raises:

Returns:

a newly allocated string or None on error

Return type:

Converts a SR-IOV virtual function object to its string representation.

New in version 1.14.

NM.utils_ssid_to_utf8(ssid)¶

Parameters:: ssid (bytes) – pointer to a buffer containing the SSID data
Returns:: an allocated string containing a UTF-8 representation of the SSID, which must be freed by the caller using GLib.free(). Returns None on errors.
Return type:: str

Wi-Fi SSIDs are byte arrays, they are _not_ strings. Thus, an SSID may contain embedded NULLs and other unprintable characters. Often it is useful to print the SSID out for debugging purposes, but that should be the _only_ use of this function. Do not use this function for any persistent storage of the SSID, since the printable SSID returned from this function cannot be converted back into the real SSID of the access point.

This function does almost everything humanly possible to convert the input into a printable UTF-8 string, using roughly the following procedure:

if the input data is already UTF-8 safe, no conversion is performed

2) attempts to get the current system language from the LANG environment variable, and depending on the language, uses a table of alternative encodings to try. For example, if LANG=hu_HU, the table may first try the ISO-8859-2 encoding, and if that fails, try the Windows-1250 encoding. If all fallback encodings fail, replaces non-UTF-8 characters with ‘?’. 3) If the system language was unable to be determined, falls back to the ISO-8859-1 encoding, then to the Windows-1251 encoding. 4) If step 3 fails, replaces non-UTF-8 characters with ‘?’.

Again, this function should be used for debugging and display purposes _only_.

NM.utils_tc_action_from_str(str)¶

Parameters:: str (str) – the string representation of a action
Raises:: GLib.Error
Returns:: the NM.TCAction or None
Return type:: NM.TCAction

Parses the tc style string action representation of the queueing discipline to a NM.TCAction instance. Supports a subset of the tc language.

New in version 1.12.

NM.utils_tc_action_to_str(action)¶

Parameters:: action (NM.TCAction) – the NM.TCAction
Raises:: GLib.Error
Returns:: formatted string or None
Return type:: str

Turns the NM.TCAction into a tc style string representation of the queueing discipline.

New in version 1.12.

NM.utils_tc_qdisc_from_str(str)¶

Parameters:: str (str) – the string representation of a qdisc
Raises:: GLib.Error
Returns:: the NM.TCQdisc or None
Return type:: NM.TCQdisc

Parses the tc style string qdisc representation of the queueing discipline to a NM.TCQdisc instance. Supports a subset of the tc language.

New in version 1.12.

NM.utils_tc_qdisc_to_str(qdisc)¶

Parameters:: qdisc (NM.TCQdisc) – the NM.TCQdisc
Raises:: GLib.Error
Returns:: formatted string or None
Return type:: str

Turns the NM.TCQdisc into a tc style string representation of the queueing discipline.

New in version 1.12.

NM.utils_tc_tfilter_from_str(str)¶

Parameters:: str (str) – the string representation of a tfilter
Raises:: GLib.Error
Returns:: the NM.TCTfilter or None
Return type:: NM.TCTfilter

Parses the tc style string tfilter representation of the queueing discipline to a NM.TCTfilter instance. Supports a subset of the tc language.

New in version 1.12.

NM.utils_tc_tfilter_to_str(tfilter)¶

Parameters:: tfilter (NM.TCTfilter) – the NM.TCTfilter
Raises:: GLib.Error
Returns:: formatted string or None
Return type:: str

Turns the NM.TCTfilter into a tc style string representation of the queueing discipline.

New in version 1.12.

NM.utils_uuid_generate()¶

Returns:: a newly allocated UUID suitable for use as the NM.SettingConnection object’s NM.SettingConnection :id: property. Should be freed with GLib.free()
Return type:: str

NM.utils_version()¶

Returns:: the version ID of the libnm version. That is, the %NM_VERSION at runtime.
Return type:: int

New in version 1.6.

NM.utils_wep_key_valid(key, wep_type)¶

Parameters:

key (str) – a string that might be a WEP key
wep_type (NM.WepKeyType) – the NM.WepKeyType type of the WEP key

Returns:

True if key is a WEP key, False if not

Return type:

Checks if key is a valid WEP key

NM.utils_wifi_2ghz_freqs()¶

Returns:: zero-terminated array of frequencies numbers (in MHz)
Return type:: int

Utility function to return 2.4 GHz Wi-Fi frequencies (802.11bg band).

New in version 1.2.

NM.utils_wifi_5ghz_freqs()¶

Returns:: zero-terminated array of frequencies numbers (in MHz)
Return type:: int

Utility function to return 5 GHz Wi-Fi frequencies (802.11a band).

New in version 1.2.

NM.utils_wifi_channel_to_freq(channel, band)¶

Parameters:

channel (int) – channel
band (str) – frequency band for wireless (“a” or “bg”)

Returns:

the frequency represented by the channel of the band, or -1 when the freq is invalid, or 0 when the band is invalid

Return type:

int

Utility function to translate a Wi-Fi channel to its corresponding frequency.

NM.utils_wifi_find_next_channel(channel, direction, band)¶

Parameters:

channel (int) – current channel
direction (int) – whether going downward (0 or less) or upward (1 or more)
band (str) – frequency band for wireless (“a” or “bg”)

Returns:

the next channel in the specified direction or 0

Return type:

int

Utility function to find out next/previous Wi-Fi channel for a channel.

NM.utils_wifi_freq_to_channel(freq)¶

Parameters:: freq (int) – frequency
Returns:: the channel represented by the frequency or 0
Return type:: int

Utility function to translate a Wi-Fi frequency to its corresponding channel.

NM.utils_wifi_is_channel_valid(channel, band)¶

Parameters:

channel (int) – channel
band (str) – frequency band for wireless (“a” or “bg”)

Returns:

True or False

Return type:

Utility function to verify Wi-Fi channel validity.

NM.utils_wifi_strength_bars(strength)¶

Parameters:: strength (int) – the access point strength, from 0 to 100
Returns:: the graphical representation of the access point strength
Return type:: str

Converts strength into a 4-character-wide graphical representation of strength suitable for printing to stdout.

Previous versions used to take a guess at the terminal type and possibly return a wide UTF-8 encoded string. Now it always returns a 7-bit clean strings of one to 0 to 4 asterisks. Users that actually need the functionality are encouraged to make their implementations instead.

NM.utils_wpa_psk_valid(psk)¶

Parameters:: psk (str) – a string that might be a WPA PSK
Returns:: True if psk is a WPA PSK, False if not
Return type:: bool

Checks if psk is a valid WPA PSK

NM.vpn_editor_plugin_load(plugin_name, check_service)¶

Parameters:

plugin_name (str) – The name of the shared library to load. This path will be directly passed to dlopen() without further checks.
check_service (str) – if not-null, check that the loaded plugin advertises the given service.

Raises:

Returns:

a new plugin instance or None on error.

Return type:

NM.VpnEditorPlugin

Load the shared library plugin_name and create a new NM.VpnEditorPlugin instance via the #NMVpnEditorPluginFactory function.

This is similar to NM.VpnEditorPlugin.load_from_file(), but it does no validation of the plugin name, instead passes it directly to dlopen(). If you have the full path to a plugin file, NM.VpnEditorPlugin.load_from_file() is preferred.

New in version 1.4.

NM.vpn_editor_plugin_load_from_file(plugin_name, check_service, check_owner, check_file, *user_data)¶

Parameters:

plugin_name (str) – The path or name of the shared library to load. The path must either be an absolute filename to an existing file. Alternatively, it can be the name (without path) of a library in the plugin directory of NetworkManager.
check_service (str) – if not-null, check that the loaded plugin advertises the given service.
check_owner (int) – if non-negative, check whether the file is owned by UID check_owner or by root. In this case also check that the file is not writable by anybody else.
check_file (NM.UtilsCheckFilePredicate) – optional callback to validate the file prior to loading the shared library.
user_data (object or None) – user data for check_file

Raises: