GI.NM.Functions

Methods

connWireguardImport

connWireguardImport

Arguments

:: (HasCallStack, MonadIO m)

=> Text

filename: name of the file to attempt to read into a new Connection

-> m Connection

Returns: a new Connection imported from path, or Nothing on error or if the file with filename was not recognized as a WireGuard config (Can throw GError)

No description available in the introspection data.

Since: 1.40

ethtoolOptnameIsChannels

ethtoolOptnameIsChannels

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

optname: the option name to check

-> m Bool

Returns: True, if optname is valid

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

Since: 1.46

ethtoolOptnameIsCoalesce

ethtoolOptnameIsCoalesce

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

optname: the option name to check

-> m Bool

Returns: True, if optname is valid

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

Since: 1.26

ethtoolOptnameIsEee

ethtoolOptnameIsEee

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

optname: the option name to check

-> m Bool

Returns: True, if optname is valid

Checks whether optname is a valid option name for an eee setting.

Since: 1.46

ethtoolOptnameIsFeature

ethtoolOptnameIsFeature

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

optname: the option name to check

-> m Bool

Returns: True, if optname is valid

Note that ethtoolOptnameIsFeature was first added to the libnm header files in 1.14.0 but forgot to actually add to the library. This happened belatedly in 1.20.0 and the stable versions 1.18.2, 1.16.4 and 1.14.8 (with linker version "libnm_1_14_8").

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

Since: 1.20

ethtoolOptnameIsPause

ethtoolOptnameIsPause

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

optname: the option name to check

-> m Bool

Returns: True, if optname is valid

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

Since: 1.32

ethtoolOptnameIsRing

ethtoolOptnameIsRing

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

optname: the option name to check

-> m Bool

Returns: True, if optname is valid

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

Since: 1.26

keyfileRead

keyfileRead

Arguments

:: (HasCallStack, MonadIO m)

=> KeyFile

keyfile: the keyfile from which to create the connection

-> Text

baseDir: when reading certificates from files with relative name, the relative path is made absolute using baseDir. This must be an absolute path.

-> [KeyfileHandlerFlags]

handlerFlags: the KeyfileHandlerFlags.

-> Maybe KeyfileReadHandler

handler: read handler

-> m Connection

Returns: on success, returns the created connection. (Can throw GError)

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

Since: 1.30

keyfileWrite

keyfileWrite

Arguments

:: (HasCallStack, MonadIO m, IsConnection a)

=> a

connection: the Connection to persist to keyfile.

-> [KeyfileHandlerFlags]

handlerFlags: the KeyfileHandlerFlags.

-> Maybe KeyfileWriteHandler

handler: optional handler for events and to override the default behavior.

-> m KeyFile

Returns: a new KeyFile or Nothing on error. (Can throw GError)

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

Since: 1.30

utilsApModeSecurityValid

utilsApModeSecurityValid

Arguments

:: (HasCallStack, MonadIO m)

=> UtilsSecurityType

type: the security type to check device capabilities against, e.g. NMU_SEC_STATIC_WEP

-> [DeviceWifiCapabilities]

wifiCaps: bitfield of the capabilities of the specific Wi-Fi device, e.g. NM_WIFI_DEVICE_CAP_CIPHER_WEP40

-> m Bool

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

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.

utilsBase64secretDecode

utilsBase64secretDecode

Arguments

:: (HasCallStack, MonadIO m)

=> Text

base64Key: the (possibly invalid) base64 encode key.

-> CSize

requiredKeyLen: the expected (binary) length of the key after decoding. If the length does not match, the validation fails.

-> m (Bool, Word8)

Returns: True if the input key is a valid base64 encoded key with requiredKeyLen bytes.

No description available in the introspection data.

Since: 1.16

utilsBin2hexstr

utilsBin2hexstr

Arguments

:: (HasCallStack, MonadIO m)

=> ByteString

src: an array of bytes

-> Int32

finalLen: an index where to cut off the returned string, or -1

-> m Text

Returns: the textual form of bytes

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

utilsBondModeIntToString

utilsBondModeIntToString

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

mode: bonding mode as a numeric value

-> m Text

Returns: bonding mode string, or NULL on error

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

Since: 1.2

utilsBondModeStringToInt

utilsBondModeStringToInt

Arguments

:: (HasCallStack, MonadIO m)

=> Text

mode: bonding mode as string

-> m Int32

Returns: numeric bond mode, or -1 on error

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

Since: 1.2

utilsCheckVirtualDeviceCompatibility

utilsCheckVirtualDeviceCompatibility

Arguments

:: (HasCallStack, MonadIO m)

=> GType

virtualType: a virtual connection type

-> GType

otherType: a connection type to test against virtualType

-> m Bool

Returns: True or False

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

If virtualType is NM_TYPE_SETTING_VLAN, then this checks if otherType is a valid type for the parent of a VLAN.

If virtualType is a "controller" type (eg, NM_TYPE_SETTING_BRIDGE), then this checks if otherType is a valid type for a port of that controller.

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

utilsEnsureGtypes

utilsEnsureGtypes :: (HasCallStack, MonadIO m) => m ()

This ensures that all NMSetting GTypes are created. For example, after this call, g_type_from_name("NMSettingConnection") will work.

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

Since: 1.42

utilsEnumFromStr

utilsEnumFromStr

Arguments

:: (HasCallStack, MonadIO m)

=> GType

type: the GType of the enum

-> Text

str: the input string

-> m (Bool, Int32, Maybe Text)

Returns: True if the conversion was successful, False otherwise

Converts a string to the matching enum value.

If the enum is a G_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 errToken.

Since: 1.2

utilsEnumGetValues

utilsEnumGetValues

Arguments

:: (HasCallStack, MonadIO m)

=> GType

type: the GType of the enum

-> Int32

from: the first element to be returned

-> Int32

to: the last element to be returned

-> m [Text]

Returns: a NULL-terminated dynamically-allocated array of static strings or Nothing on error

Returns the list of possible values for a given enum.

Since: 1.2

utilsEnumToStr

utilsEnumToStr

Arguments

:: (HasCallStack, MonadIO m)

=> GType

type: the GType of the enum

-> Int32

value: the value to be translated

-> m Text

Returns: a newly allocated string or Nothing

Converts an enum value to its string representation. If the enum is a G_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.

Since: 1.2

utilsEscapeSsid

utilsEscapeSsid

Arguments

:: (HasCallStack, MonadIO m)

=> ByteString

ssid: pointer to a buffer containing the SSID data

-> m Text

Returns: pointer to the escaped SSID, which uses an internal static buffer and will be overwritten by subsequent calls to this function

Deprecated: (Since version 1.46)use utilsSsidToUtf8 or utilsBin2hexstr.

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.

utilsFileIsCertificate

utilsFileIsCertificate

Arguments

:: (HasCallStack, MonadIO m)

=> Text

filename: name of the file to test

-> m Bool

Returns: True if the file is a certificate, False if it is not

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.

utilsFileIsPkcs12

utilsFileIsPkcs12

Arguments

:: (HasCallStack, MonadIO m)

=> Text

filename: name of the file to test

-> m Bool

Returns: True if the file is PKCS#<!-- -->12, False if it is not

Tests if filename is a PKCS#<!-- -->12 file.

utilsFileIsPrivateKey

utilsFileIsPrivateKey

Arguments

:: (HasCallStack, MonadIO m)

=> Text

filename: name of the file to test

-> m (Bool, Bool)

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

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.

utilsFileSearchInPaths

utilsFileSearchInPaths

Arguments

:: (HasCallStack, MonadIO m)

=> Text

progname: the helper program name, like "iptables" Must be a non-empty string, without path separator (/).

-> Maybe Text

tryFirst: a custom path to try first before searching. It is silently ignored if it is empty or not an absolute path.

-> Maybe Text

paths: a Nothing terminated list of search paths. Can be empty or Nothing, in which case only tryFirst is checked.

-> [FileTest]

fileTestFlags: the flags passed to fileTest when searching for progname. Set it to 0 to skip the fileTest.

-> UtilsFileSearchInPathsPredicate

predicate: if given, pass the file name to this function for additional checks. This check is performed after the check for fileTestFlags. You cannot omit both fileTestFlags and predicate.

-> m Text

Returns: the full path to the helper, if found, or Nothing if not found. The returned string is not owned by the caller, but later invocations of the function might overwrite it. (Can throw GError)

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

utilsGetTimestampMsec

utilsGetTimestampMsec

Arguments

:: (HasCallStack, MonadIO m)

=> m Int64

Returns: time in milliseconds

Gets current time in milliseconds of CLOCK_BOOTTIME.

Since: 1.12

utilsHexstr2bin

utilsHexstr2bin

Arguments

:: (HasCallStack, MonadIO m)

=> Text

hex: a string of hexadecimal characters with optional ':' separators

-> m Bytes

Returns: the converted bytes, or Nothing on error

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

utilsHwaddrAtoba

utilsHwaddrAtoba

Arguments

:: (HasCallStack, MonadIO m)

=> Text

asc: the ASCII representation of a hardware address

-> CSize

length: the expected length in bytes of the result

-> m ByteString

Returns: a new ByteArray, or Nothing if asc couldn't be parsed

Parses asc and converts it to binary form in a ByteArray. See utilsHwaddrAton if you don't want a ByteArray.

utilsHwaddrAton

utilsHwaddrAton

Arguments

:: (HasCallStack, MonadIO m)

=> Text

asc: the ASCII representation of a hardware address

-> ByteString

buffer: buffer to store the result into

-> m Word8

Returns: buffer, or Nothing if asc couldn't be parsed or would be shorter or longer than length.

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

utilsHwaddrCanonical

utilsHwaddrCanonical

Arguments

:: (HasCallStack, MonadIO m)

=> Text

asc: the ASCII representation of a hardware address

-> Int64

length: the length of address that asc is expected to convert to (or -1 to accept any length up to UTILS_HWADDR_LEN_MAX)

-> m Text

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

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

utilsHwaddrLen

utilsHwaddrLen

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

type: the type of address; either <literal>ARPHRD_ETHER</literal> or <literal>ARPHRD_INFINIBAND</literal>

-> m CSize

Returns: the length or zero if the type is unrecognized.

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 <literal>ARPHRD_ETHER</literal> or <literal>ARPHRD_INFINIBAND</literal>.

utilsHwaddrMatches

utilsHwaddrMatches

Arguments

:: (HasCallStack, MonadIO m)

=> Ptr ()

hwaddr1: pointer to a binary or ASCII hardware address, or Nothing

-> Int64

hwaddr1Len: size of hwaddr1, or -1 if hwaddr1 is ASCII

-> Ptr ()

hwaddr2: pointer to a binary or ASCII hardware address, or Nothing

-> Int64

hwaddr2Len: size of hwaddr2, or -1 if hwaddr2 is ASCII

-> m Bool

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

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

1. If hwaddr1Len or hwaddr2Len is -1, then the corresponding address is assumed to be ASCII rather than binary, and will be converted to binary before being compared.
2. If hwaddr1 or hwaddr2 is Nothing, it is treated instead as though it was a zero-filled buffer hwaddr1Len or hwaddr2Len bytes long.
3. If hwaddr1 and hwaddr2 are InfiniBand hardware addresses (that is, if they are <literal>INFINIBAND_ALEN</literal> 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 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.)

utilsHwaddrNtoa

utilsHwaddrNtoa

Arguments

:: (HasCallStack, MonadIO m)

=> ByteString

addr: a binary hardware address

-> m Text

Returns: the textual form of addr

Converts addr to textual form.

utilsHwaddrValid

utilsHwaddrValid

Arguments

:: (HasCallStack, MonadIO m)

=> Text

asc: the ASCII representation of a hardware address

-> Int64

length: the length of address that asc is expected to convert to (or -1 to accept any length up to UTILS_HWADDR_LEN_MAX)

-> m Bool

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

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

utilsIfaceValidName

utilsIfaceValidName

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

name: Name of interface

-> m Bool

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

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

Deprecated: (Since version 1.6)Use utilsIsValidIfaceName instead, with better error reporting.

Validate the network interface name.

utilsIp4AddressesFromVariant

utilsIp4AddressesFromVariant

Arguments

:: (HasCallStack, MonadIO m)

=> GVariant

value: a GVariant of type 'aau'

-> m ([IPAddress], Maybe Text)

Returns: a newly allocated PtrArray of IPAddress objects

Utility function to convert a GVariant of type 'aau' representing a list of NetworkManager IPv4 addresses (which are tuples of address, prefix, and gateway) into a PtrArray of IPAddress objects. The "gateway" field of the first address (if set) will be returned in outGateway; 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)

utilsIp4AddressesToVariant

utilsIp4AddressesToVariant

Arguments

:: (HasCallStack, MonadIO m)

=> [IPAddress]

addresses: an array of IPAddress objects

-> Maybe Text

gateway: the gateway IP address

-> m GVariant

Returns: a new floating GVariant representing addresses.

Utility function to convert a PtrArray of IPAddress objects representing IPv4 addresses into a GVariant 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-Nothing). In all of the other addresses, that field will be 0.

utilsIp4DnsFromVariant

utilsIp4DnsFromVariant

Arguments

:: (HasCallStack, MonadIO m)

=> GVariant

value: a GVariant of type 'au'

-> m Text

Returns: a Nothing-terminated array of IP address strings.

Utility function to convert a GVariant 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)

utilsIp4DnsToVariant

utilsIp4DnsToVariant

Arguments

:: (HasCallStack, MonadIO m)

=> Text

dns: an array of IP address strings

-> m GVariant

Returns: a new floating GVariant representing dns.

Utility function to convert an array of IP address strings int a GVariant of type 'au' representing an array of IPv4 addresses.

utilsIp4GetDefaultPrefix

utilsIp4GetDefaultPrefix

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

ip: an IPv4 address (in network byte order)

-> m Word32

Returns: the default class prefix for the given IP

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.

utilsIp4NetmaskToPrefix

utilsIp4NetmaskToPrefix

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

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

-> m Word32

Returns: the CIDR prefix represented by the netmask

No description available in the introspection data.

utilsIp4PrefixToNetmask

utilsIp4PrefixToNetmask

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

prefix: a CIDR prefix, must be not larger than 32.

-> m Word32

Returns: the netmask represented by the prefix, in network byte order

No description available in the introspection data.

utilsIp4RoutesFromVariant

utilsIp4RoutesFromVariant

Arguments

:: (HasCallStack, MonadIO m)

=> GVariant

value: GVariant of type 'aau'

-> m [IPRoute]

Returns: a newly allocated PtrArray of IPRoute objects

Utility function to convert a GVariant of type 'aau' representing an array of NetworkManager IPv4 routes (which are tuples of route, prefix, next hop, and metric) into a PtrArray of 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)

utilsIp4RoutesToVariant

utilsIp4RoutesToVariant

Arguments

:: (HasCallStack, MonadIO m)

=> [IPRoute]

routes: an array of NMIP4Route objects

-> m GVariant

Returns: a new floating GVariant representing routes.

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

utilsIp6AddressesFromVariant

utilsIp6AddressesFromVariant

Arguments

:: (HasCallStack, MonadIO m)

=> GVariant

value: a GVariant of type 'a(ayuay)'

-> m ([IPAddress], Maybe Text)

Returns: a newly allocated PtrArray of IPAddress objects

Utility function to convert a GVariant of type 'a(ayuay)' representing a list of NetworkManager IPv6 addresses (which are tuples of address, prefix, and gateway) into a PtrArray of IPAddress objects. The "gateway" field of the first address (if set) will be returned in outGateway; 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)

utilsIp6AddressesToVariant

utilsIp6AddressesToVariant

Arguments

:: (HasCallStack, MonadIO m)

=> [IPAddress]

addresses: an array of IPAddress objects

-> Maybe Text

gateway: the gateway IP address

-> m GVariant

Returns: a new floating GVariant representing addresses.

Utility function to convert a PtrArray of IPAddress objects representing IPv6 addresses into a GVariant 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-Nothing). In all of the other addresses, that field will be all 0s.

utilsIp6DnsFromVariant

utilsIp6DnsFromVariant

Arguments

:: (HasCallStack, MonadIO m)

=> GVariant

value: a GVariant of type 'aay'

-> m Text

Returns: a Nothing-terminated array of IP address strings.

Utility function to convert a GVariant 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)

utilsIp6DnsToVariant

utilsIp6DnsToVariant

Arguments

:: (HasCallStack, MonadIO m)

=> Text

dns: an array of IP address strings

-> m GVariant

Returns: a new floating GVariant representing dns.

Utility function to convert an array of IP address strings int a GVariant of type 'aay' representing an array of IPv6 addresses.

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

utilsIp6RoutesFromVariant

utilsIp6RoutesFromVariant

Arguments

:: (HasCallStack, MonadIO m)

=> GVariant

value: GVariant of type 'a(ayuayu)'

-> m [IPRoute]

Returns: a newly allocated PtrArray of IPRoute objects

Utility function to convert a GVariant of type 'a(ayuayu)' representing an array of NetworkManager IPv6 routes (which are tuples of route, prefix, next hop, and metric) into a PtrArray of 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)

utilsIp6RoutesToVariant

utilsIp6RoutesToVariant

Arguments

:: (HasCallStack, MonadIO m)

=> [IPRoute]

routes: an array of IPRoute objects

-> m GVariant

Returns: a new floating GVariant representing routes.

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

utilsIpAddressesFromVariant

utilsIpAddressesFromVariant

Arguments

:: (HasCallStack, MonadIO m)

=> GVariant

value: a GVariant of type 'aa{sv}'

-> Int32

family: an IP address family

-> m [IPAddress]

Returns: a newly allocated PtrArray of IPAddress objects

Utility function to convert a GVariant representing a list of new-style NetworkManager IPv4 or IPv6 addresses (as described in the documentation for utilsIpAddressesToVariant) into a PtrArray of 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)

Since: 1.42

utilsIpAddressesToVariant

utilsIpAddressesToVariant

Arguments

:: (HasCallStack, MonadIO m)

=> [IPAddress]

addresses: an array of IPAddress objects

-> m GVariant

Returns: a new floating GVariant representing addresses.

Utility function to convert a PtrArray of IPAddress objects representing IPv4 or IPv6 addresses into a GVariant 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.

Since: 1.42

utilsIpRoutesFromVariant

utilsIpRoutesFromVariant

Arguments

:: (HasCallStack, MonadIO m)

=> GVariant

value: a GVariant of type 'aa{sv}'

-> Int32

family: an IP address family

-> m [IPRoute]

Returns: a newly allocated PtrArray of IPRoute objects

Utility function to convert a GVariant representing a list of new-style NetworkManager IPv4 or IPv6 addresses (as described in the documentation for utilsIpRoutesToVariant) into a PtrArray of 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)

Since: 1.42

utilsIpRoutesToVariant

utilsIpRoutesToVariant

Arguments

:: (HasCallStack, MonadIO m)

=> [IPRoute]

routes: an array of IPRoute objects

-> m GVariant

Returns: a new floating GVariant representing routes.

Utility function to convert a PtrArray of IPRoute objects representing IPv4 or IPv6 routes into a GVariant 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.

Since: 1.42

utilsIpaddrValid

utilsIpaddrValid

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

family: <literal>AF_INET</literal> or <literal>AF_INET6</literal>, or <literal>AF_UNSPEC</literal> to accept either

-> Text

ip: an IP address

-> m Bool

Returns: True or False

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

utilsIsEmptySsid

utilsIsEmptySsid

Arguments

:: (HasCallStack, MonadIO m)

=> ByteString

ssid: pointer to a buffer containing the SSID data

-> m Bool

Returns: True if the SSID is "empty", False if it is not

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.

utilsIsJsonObject

utilsIsJsonObject

Arguments

:: (HasCallStack, MonadIO m)

=> Text

str: the JSON string to test

-> m ()

(Can throw GError)

No description available in the introspection data.

Since: 1.6

utilsIsUuid

utilsIsUuid

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

str: a string that might be a UUID

-> m Bool

Returns: True if str is a UUID, False if not

In older versions, utilsIsUuid did not accept Nothing as str argument. Don't pass Nothing if you run against older versions of libnm.

Deprecated: (Since version 1.32)older versions of NetworkManager had a wrongunderstanding of what makes a valid UUID. This function can thusaccept some inputs as valid, which in fact are not valid UUIDs.

Checks if str is a UUID

utilsIsValidIfaceName

utilsIsValidIfaceName

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

name: Name of interface

-> m ()

(Can throw GError)

Validate the network interface name.

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

Since: 1.6

utilsPrint

utilsPrint

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

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

-> Text

msg: the message to print. The function does not append a trailing newline.

-> m ()

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 utilsPrint, 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 &lt;error&gt; messages imply an unexpected data on the D-Bus API (due to a bug). &lt;warn&gt; 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 outputMode 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.

Since: 1.30

utilsSameSsid

utilsSameSsid

Arguments

:: (HasCallStack, MonadIO m)

=> ByteString

ssid1: the first SSID to compare

-> ByteString

ssid2: the second SSID to compare

-> Bool

ignoreTrailingNull: True to ignore one trailing NULL byte

-> m Bool

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

Earlier versions of the Linux kernel added a NULL 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.

utilsSecurityValid

utilsSecurityValid

Arguments

:: (HasCallStack, MonadIO m)

=> UtilsSecurityType

type: the security type to check AP flags and device capabilities against, e.g. NMU_SEC_STATIC_WEP

-> [DeviceWifiCapabilities]

wifiCaps: bitfield of the capabilities of the specific Wi-Fi device, e.g. NM_WIFI_DEVICE_CAP_CIPHER_WEP40

-> Bool

haveAp: whether the apFlags, apWpa, and apRsn arguments are valid

-> Bool

adhoc: whether the capabilities being tested are from an Ad-Hoc AP (IBSS)

-> [NM80211ApFlags]

apFlags: bitfield of AP capabilities, e.g. NM_802_11_AP_FLAGS_PRIVACY

-> [NM80211ApSecurityFlags]

apWpa: bitfield of AP capabilities derived from the AP's WPA beacon, e.g. (NM_802_11_AP_SEC_PAIR_TKIP | NM_802_11_AP_SEC_KEY_MGMT_PSK)

-> [NM80211ApSecurityFlags]

apRsn: bitfield of AP capabilities derived from the AP's RSN/WPA2 beacon, e.g. (NM_802_11_AP_SEC_PAIR_CCMP | NM_802_11_AP_SEC_PAIR_TKIP)

-> m Bool

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

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 utilsApModeSecurityValid instead.

utilsSriovVfFromStr

utilsSriovVfFromStr

Arguments

:: (HasCallStack, MonadIO m)

=> Text

str: the input string

-> m SriovVF

Returns: the virtual function object (Can throw GError)

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

Since: 1.14

utilsSriovVfToStr

utilsSriovVfToStr

Arguments

:: (HasCallStack, MonadIO m)

=> SriovVF

vf: the NMSriovVF

-> Bool

omitIndex: if True, the VF index will be omitted from output string

-> m Text

Returns: a newly allocated string or Nothing on error (Can throw GError)

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

Since: 1.14

utilsSsidToUtf8

utilsSsidToUtf8

Arguments

:: (HasCallStack, MonadIO m)

=> ByteString

ssid: pointer to a buffer containing the SSID data

-> m Text

Returns: an allocated string containing a UTF-8 representation of the SSID, which must be freed by the caller using free. Returns Nothing on errors.

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

utilsTcActionFromStr

utilsTcActionFromStr

Arguments

:: (HasCallStack, MonadIO m)

=> Text

str: the string representation of a action

-> m TCAction

Returns: the NMTCAction or Nothing (Can throw GError)

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

Since: 1.12

utilsTcActionToStr

utilsTcActionToStr

Arguments

:: (HasCallStack, MonadIO m)

=> TCAction

action: the NMTCAction

-> m Text

Returns: formatted string or Nothing (Can throw GError)

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

Since: 1.12

utilsTcQdiscFromStr

utilsTcQdiscFromStr

Arguments

:: (HasCallStack, MonadIO m)

=> Text

str: the string representation of a qdisc

-> m TCQdisc

Returns: the NMTCQdisc or Nothing (Can throw GError)

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

Since: 1.12

utilsTcQdiscToStr

utilsTcQdiscToStr

Arguments

:: (HasCallStack, MonadIO m)

=> TCQdisc

qdisc: the NMTCQdisc

-> m Text

Returns: formatted string or Nothing (Can throw GError)

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

Since: 1.12

utilsTcTfilterFromStr

utilsTcTfilterFromStr

Arguments

:: (HasCallStack, MonadIO m)

=> Text

str: the string representation of a tfilter

-> m TCTfilter

Returns: the NMTCTfilter or Nothing (Can throw GError)

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

Since: 1.12

utilsTcTfilterToStr

utilsTcTfilterToStr

Arguments

:: (HasCallStack, MonadIO m)

=> TCTfilter

tfilter: the NMTCTfilter

-> m Text

Returns: formatted string or Nothing (Can throw GError)

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

Since: 1.12

utilsUuidGenerate

utilsUuidGenerate

Arguments

:: (HasCallStack, MonadIO m)

=> m Text

Returns: a newly allocated UUID suitable for use as the SettingConnection object's SettingConnection:id: property. Should be freed with free

No description available in the introspection data.

utilsVersion

utilsVersion

Arguments

:: (HasCallStack, MonadIO m)

=> m Word32

Returns: the version ID of the libnm version. That is, the NM_VERSION at runtime.

No description available in the introspection data.

Since: 1.6

utilsWepKeyValid

utilsWepKeyValid

Arguments

:: (HasCallStack, MonadIO m)

=> Text

key: a string that might be a WEP key

-> WepKeyType

wepType: the WepKeyType type of the WEP key

-> m Bool

Returns: True if key is a WEP key, False if not

Checks if key is a valid WEP key

utilsWifi2ghzFreqs

utilsWifi2ghzFreqs

Arguments

:: (HasCallStack, MonadIO m)

=> m Word32

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

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

Since: 1.2

utilsWifi5ghzFreqs

utilsWifi5ghzFreqs

Arguments

:: (HasCallStack, MonadIO m)

=> m Word32

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

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

Since: 1.2

utilsWifiChannelToFreq

utilsWifiChannelToFreq

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

channel: channel

-> Text

band: frequency band for wireless ("a" or "bg")

-> m Word32

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

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

utilsWifiFindNextChannel

utilsWifiFindNextChannel

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

channel: current channel

-> Int32

direction: whether going downward (0 or less) or upward (1 or more)

-> Text

band: frequency band for wireless ("a" or "bg")

-> m Word32

Returns: the next channel in the specified direction or 0

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

utilsWifiFreqToChannel

utilsWifiFreqToChannel

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

freq: frequency

-> m Word32

Returns: the channel represented by the frequency or 0

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

utilsWifiIsChannelValid

utilsWifiIsChannelValid

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

channel: channel

-> Text

band: frequency band for wireless ("a" or "bg")

-> m Bool

Returns: True or False

Utility function to verify Wi-Fi channel validity.

utilsWifiStrengthBars

utilsWifiStrengthBars

Arguments

:: (HasCallStack, MonadIO m)

=> Word8

strength: the access point strength, from 0 to 100

-> m Text

Returns: the graphical representation of the access point strength

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.

utilsWpaPskValid

utilsWpaPskValid

Arguments

:: (HasCallStack, MonadIO m)

=> Text

psk: a string that might be a WPA PSK

-> m Bool

Returns: True if psk is a WPA PSK, False if not

Checks if psk is a valid WPA PSK