Functions

  agent_manager_error_quark ()
  bridge_vlan_from_str (str)
  client_error_quark ()
  connection_error_quark ()
  crypto_error_quark ()
  device_error_quark ()
  ethtool_optname_is_coalesce (optname)
  ethtool_optname_is_feature (optname)
  ethtool_optname_is_ring (optname)
  ip_route_attribute_validate (name, value, family)
  ip_route_get_variant_attribute_spec ()
  ip_routing_rule_from_string (str, to_string_flags, extra_args)
  manager_error_quark ()
  secret_agent_error_quark ()
  settings_error_quark ()
  sriov_vf_attribute_validate (name, value)
  utils_ap_mode_security_valid (type, wifi_caps)
  utils_base64secret_decode (base64_key, required_key_len, out_key)
  utils_bin2hexstr (src, final_len)
  utils_bond_mode_int_to_string (mode)
  utils_bond_mode_string_to_int (mode)
  utils_check_virtual_device_compatibility (virtual_type, other_type)
  utils_enum_from_str (type, str)
  utils_enum_get_values (type, from_, to)
  utils_enum_to_str (type, value)
  utils_escape_ssid (ssid)
  utils_file_is_certificate (filename)
  utils_file_is_pkcs12 (filename)
  utils_file_is_private_key (filename)
  utils_file_search_in_paths (progname, try_first, paths, file_test_flags, predicate, *user_data)
  utils_format_variant_attributes (attributes, attr_separator, key_value_separator)
  utils_get_timestamp_msec ()
  utils_hexstr2bin (hex)
  utils_hwaddr_atoba (asc, length)
  utils_hwaddr_aton (asc, buffer)
  utils_hwaddr_canonical (asc, length)
  utils_hwaddr_len (type)
  utils_hwaddr_matches (hwaddr1, hwaddr1_len, hwaddr2, hwaddr2_len)
  utils_hwaddr_ntoa (addr)
  utils_hwaddr_valid (asc, length)
  utils_iface_valid_name (name)
  utils_ip4_addresses_from_variant (value)
  utils_ip4_addresses_to_variant (addresses, gateway)
  utils_ip4_dns_from_variant (value)
  utils_ip4_dns_to_variant (dns)
  utils_ip4_get_default_prefix (ip)
  utils_ip4_netmask_to_prefix (netmask)
  utils_ip4_prefix_to_netmask (prefix)
  utils_ip4_routes_from_variant (value)
  utils_ip4_routes_to_variant (routes)
  utils_ip6_addresses_from_variant (value)
  utils_ip6_addresses_to_variant (addresses, gateway)
  utils_ip6_dns_from_variant (value)
  utils_ip6_dns_to_variant (dns)
  utils_ip6_routes_from_variant (value)
  utils_ip6_routes_to_variant (routes)
  utils_ip_addresses_from_variant (value, family)
  utils_ip_addresses_to_variant (addresses)
  utils_ip_routes_from_variant (value, family)
  utils_ip_routes_to_variant (routes)
  utils_ipaddr_valid (family, ip)
  utils_is_empty_ssid (ssid)
  utils_is_json_object (str)
  utils_is_uuid (str)
  utils_is_valid_iface_name (name)
  utils_parse_variant_attributes (string, attr_separator, key_value_separator, ignore_unknown, spec)
  utils_same_ssid (ssid1, ssid2, ignore_trailing_null)
  utils_security_valid (type, wifi_caps, have_ap, adhoc, ap_flags, ap_wpa, ap_rsn)
  utils_sriov_vf_from_str (str)
  utils_sriov_vf_to_str (vf, omit_index)
  utils_ssid_to_utf8 (ssid)
  utils_tc_action_from_str (str)
  utils_tc_action_to_str (action)
  utils_tc_qdisc_from_str (str)
  utils_tc_qdisc_to_str (qdisc)
  utils_tc_tfilter_from_str (str)
  utils_tc_tfilter_to_str (tfilter)
  utils_uuid_generate ()
  utils_version ()
  utils_wep_key_valid (key, wep_type)
  utils_wifi_2ghz_freqs ()
  utils_wifi_5ghz_freqs ()
  utils_wifi_channel_to_freq (channel, band)
  utils_wifi_find_next_channel (channel, direction, band)
  utils_wifi_freq_to_channel (freq)
  utils_wifi_is_channel_valid (channel, band)
  utils_wifi_strength_bars (strength)
  utils_wpa_psk_valid (psk)
  vpn_editor_plugin_load (plugin_name, check_service)
  vpn_editor_plugin_load_from_file (plugin_name, check_service, check_owner, check_file, *user_data)
  vpn_plugin_error_quark ()

Details

NM.agent_manager_error_quark()
Return type:int
NM.bridge_vlan_from_str(str)
Parameters:str (str) – the string representation of a bridge VLAN
Raises:GLib.Error
Returns:the NM.BridgeVlan or None
Return type:NM.BridgeVlan

Parses the string representation of the queueing discipline to a NM.BridgeVlan instance.

New in version 1.18.

NM.client_error_quark()
Returns:the error quark used for NM.Client errors.
Return type:int

Registers an error quark for NM.Client if necessary.

NM.connection_error_quark()
Return type:int
NM.crypto_error_quark()
Return type:int
NM.device_error_quark()
Return type:int
NM.ethtool_optname_is_coalesce(optname)
Parameters:optname (str or None) – the option name to check
Return type:bool

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

%Returns: True, if optname is valid

New in version 1.26.

NM.ethtool_optname_is_feature(optname)
Parameters:optname (str or None) – the option name to check
Return type:bool

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

%Returns: True, if optname is valid

New in version 1.20.

NM.ethtool_optname_is_ring(optname)
Parameters:optname (str or None) – the option name to check
Return type:bool

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

%Returns: True, if optname is valid

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:

GLib.Error

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:
Raises:

GLib.Error

Returns:

the new NM.IPRoutingRule or None on error.

Return type:

NM.IPRoutingRule

New in version 1.18.

NM.manager_error_quark()
Return type:int
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:

GLib.Error

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.14.

NM.utils_ap_mode_security_valid(type, wifi_caps)
Parameters:
Returns:

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

Return type:

bool

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, out_key)
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.
  • out_key (int or None) – (out): an optional output buffer for the binary key. If given, it will be filled with exactly required_key_len bytes.
Returns:

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

Return type:

bool

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:

str

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:

bool

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_enum_from_str(type, str)
Parameters:
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)

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:
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:
Returns:

a newly allocated string or None

Return type:

str

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.

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:

GLib.Error

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:

str

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

NM.utils_format_variant_attributes(attributes, attr_separator, key_value_separator)
Parameters:
  • attributes ({object: object}) –
  • attr_separator (int) –
  • key_value_separator (int) –
Return type:

str

NM.utils_get_timestamp_msec()
Return type:int
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 sepatared 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:

str

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.
Return type:int

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

It is 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:

bool

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:

bool

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:bool

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)

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.

NM.utils_ip4_addresses_to_variant(addresses, gateway)
Parameters:
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.

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
Returns:the CIDR prefix represented by the netmask
Return type:int
NM.utils_ip4_prefix_to_netmask(prefix)
Parameters:prefix (int) – a CIDR prefix
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.

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)

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.

NM.utils_ip6_addresses_to_variant(addresses, gateway)
Parameters:
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.

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.

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.

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

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.

NM.utils_ip_routes_from_variant(value, family)
Parameters:
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 (which are tuples of destination, prefix, next hop, metric, and additional attributes) into a GLib.PtrArray of NM.IPRoute objects.

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 (which are tuples of destination, prefix, next hop, metric, and additional attributes).

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:

bool

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:bool

Checks if str is a UUID

NM.utils_is_valid_iface_name(name)
Parameters:name (str or None) – Name of interface
Raises:GLib.Error
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:bool

Validate the network interface name.

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

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:

GLib.Error

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_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:

bool

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:

bool

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:
Raises:

GLib.Error

Returns:

a newly allocated string or None on error

Return type:

str

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:

  1. 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.0.

NM.utils_wep_key_valid(key, wep_type)
Parameters:
Returns:

True if key is a WEP key, False if not

Return type:

bool

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:

bool

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:

GLib.Error

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:

GLib.Error

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.

If plugin_name is not an absolute path name, it assumes the file is in the plugin directory of NetworkManager. In any case, the call will do certain checks on the file before passing it to dlopen. A consequence for that is, that you cannot omit the “.so” suffix as you could for NM.VpnEditorPlugin.load().

New in version 1.2.

NM.vpn_plugin_error_quark()
Return type:int