NMSettingWireless: libnm Reference Manual

## NMSettingWireless NMSettingWireless — Describes connection properties for 802.11 Wi-Fi networks |

## Functions

NMSetting * | nm_setting_wireless_new ()
GBytes * | nm_setting_wireless_get_ssid ()
const char * | nm_setting_wireless_get_mode ()
const char * | nm_setting_wireless_get_band ()
guint32 | nm_setting_wireless_get_channel ()
const char * | nm_setting_wireless_get_bssid ()
guint32 | nm_setting_wireless_get_rate ()
guint32 | nm_setting_wireless_get_tx_power ()
const char * | nm_setting_wireless_get_mac_address ()
const char * | nm_setting_wireless_get_cloned_mac_address ()
const char * | nm_setting_wireless_get_generate_mac_address_mask ()
const char *const * | nm_setting_wireless_get_mac_address_blacklist ()
guint32 | nm_setting_wireless_get_num_mac_blacklist_items ()
const char * | nm_setting_wireless_get_mac_blacklist_item ()
gboolean | nm_setting_wireless_add_mac_blacklist_item ()
void | nm_setting_wireless_remove_mac_blacklist_item ()
gboolean | nm_setting_wireless_remove_mac_blacklist_item_by_value ()
void | nm_setting_wireless_clear_mac_blacklist_items ()
guint32 | nm_setting_wireless_get_mtu ()
gboolean | nm_setting_wireless_get_hidden ()
guint32 | nm_setting_wireless_get_powersave ()
NMSettingMacRandomization | nm_setting_wireless_get_mac_address_randomization ()
gboolean | nm_setting_wireless_add_seen_bssid ()
guint32 | nm_setting_wireless_get_num_seen_bssids ()
const char * | nm_setting_wireless_get_seen_bssid ()
gboolean | nm_setting_wireless_ap_security_compatible ()
NMSettingWirelessWakeOnWLan | nm_setting_wireless_get_wake_on_wlan ()
NMTernary | nm_setting_wireless_get_ap_isolation ()

## Types and Values

#define | NM_SETTING_WIRELESS_SETTING_NAME
enum | NMSettingWirelessWakeOnWLan
#define | NM_SETTING_WIRELESS_SSID
#define | NM_SETTING_WIRELESS_MODE
#define | NM_SETTING_WIRELESS_BAND
#define | NM_SETTING_WIRELESS_CHANNEL
#define | NM_SETTING_WIRELESS_BSSID
#define | NM_SETTING_WIRELESS_RATE
#define | NM_SETTING_WIRELESS_TX_POWER
#define | NM_SETTING_WIRELESS_MAC_ADDRESS
#define | NM_SETTING_WIRELESS_CLONED_MAC_ADDRESS
#define | NM_SETTING_WIRELESS_GENERATE_MAC_ADDRESS_MASK
#define | NM_SETTING_WIRELESS_MAC_ADDRESS_BLACKLIST
#define | NM_SETTING_WIRELESS_MTU
#define | NM_SETTING_WIRELESS_SEEN_BSSIDS
#define | NM_SETTING_WIRELESS_HIDDEN
#define | NM_SETTING_WIRELESS_POWERSAVE
#define | NM_SETTING_WIRELESS_MAC_ADDRESS_RANDOMIZATION
#define | NM_SETTING_WIRELESS_WAKE_ON_WLAN
#define | NM_SETTING_WIRELESS_AP_ISOLATION
#define | NM_SETTING_WIRELESS_MODE_ADHOC
#define | NM_SETTING_WIRELESS_MODE_AP
#define | NM_SETTING_WIRELESS_MODE_INFRA
#define | NM_SETTING_WIRELESS_MODE_MESH
enum | NMSettingWirelessPowersave

## Object Hierarchy

        GEnum
        ╰── NMSettingWirelessPowersave
        GFlags
        ╰── NMSettingWirelessWakeOnWLan

## Description

The NMSettingWireless object is a NMSetting subclass that describes properties necessary for connection to 802.11 Wi-Fi networks.

## Functions

### nm_setting_wireless_new ()

    NMSetting *
    nm_setting_wireless_new (void);

Creates a new NMSettingWireless object with default values.

#### Returns

the new empty NMSettingWireless object.

[transfer full]

### nm_setting_wireless_get_ssid ()

    GBytes *
    nm_setting_wireless_get_ssid (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “ssid” property of the setting.

[transfer none]

### nm_setting_wireless_get_mode ()

    const char *
    nm_setting_wireless_get_mode (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “mode” property of the setting

### nm_setting_wireless_get_band ()

    const char *
    nm_setting_wireless_get_band (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “band” property of the setting

### nm_setting_wireless_get_channel ()

    guint32
    nm_setting_wireless_get_channel (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “channel” property of the setting

### nm_setting_wireless_get_bssid ()

    const char *
    nm_setting_wireless_get_bssid (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “bssid” property of the setting

### nm_setting_wireless_get_rate ()

    guint32
    nm_setting_wireless_get_rate (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “rate” property of the setting

### nm_setting_wireless_get_tx_power ()

    guint32
    nm_setting_wireless_get_tx_power (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “tx-power” property of the setting

### nm_setting_wireless_get_mac_address ()

    const char *
    nm_setting_wireless_get_mac_address (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “mac-address” property of the setting

### nm_setting_wireless_get_cloned_mac_address ()

    const char *
    nm_setting_wireless_get_cloned_mac_address
                                   (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “cloned-mac-address” property of the setting

### nm_setting_wireless_get_generate_mac_address_mask ()

    const char *
    nm_setting_wireless_get_generate_mac_address_mask
                                   (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “generate-mac-address-mask” property of the setting

Since: 1.4

### nm_setting_wireless_get_mac_address_blacklist ()

    const char *const *
    nm_setting_wireless_get_mac_address_blacklist
                                   (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “mac-address-blacklist” property of the setting

### nm_setting_wireless_get_num_mac_blacklist_items ()

    guint32
    nm_setting_wireless_get_num_mac_blacklist_items
                                   (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the number of blacklisted MAC addresses

### nm_setting_wireless_get_mac_blacklist_item ()

    const char *
    nm_setting_wireless_get_mac_blacklist_item
                                   (NMSettingWireless *setting,
                                    guint32 idx);

#### Parameters

setting | the NMSettingWireless |
idx | the zero-based index of the MAC address entry |

#### Returns

the blacklisted MAC address string (hex-digits-and-colons notation) at index `idx`

### nm_setting_wireless_add_mac_blacklist_item ()

    gboolean
    nm_setting_wireless_add_mac_blacklist_item
                                   (NMSettingWireless *setting,
                                    const char *mac);

Adds a new MAC address to the “mac-address-blacklist” property.

#### Parameters

setting | the NMSettingWireless |
mac | the MAC address string (hex-digits-and-colons notation) to blacklist |

#### Returns

`TRUE` if the MAC address was added; `FALSE` if the MAC address is invalid or was already present

### nm_setting_wireless_remove_mac_blacklist_item ()

    void
    nm_setting_wireless_remove_mac_blacklist_item
                                   (NMSettingWireless *setting,
                                    guint32 idx);

Removes the MAC address at index `idx` from the blacklist.

#### Parameters

setting | the NMSettingWireless |
idx | index number of the MAC address |

### nm_setting_wireless_remove_mac_blacklist_item_by_value ()

    gboolean
    nm_setting_wireless_remove_mac_blacklist_item_by_value
                                   (NMSettingWireless *setting,
                                    const char *mac);

Removes the MAC address `mac` from the blacklist.

#### Parameters

setting | the NMSettingWireless |
mac | the MAC address string (hex-digits-and-colons notation) to remove from the blacklist |

#### Returns

`TRUE` if the MAC address was found and removed; `FALSE` if it was not.

### nm_setting_wireless_clear_mac_blacklist_items ()

    void
    nm_setting_wireless_clear_mac_blacklist_items
                                   (NMSettingWireless *setting);

Removes all blacklisted MAC addresses.

#### Parameters

setting | the NMSettingWireless |

### nm_setting_wireless_get_mtu ()

    guint32
    nm_setting_wireless_get_mtu (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “mtu” property of the setting

### nm_setting_wireless_get_hidden ()

    gboolean
    nm_setting_wireless_get_hidden (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “hidden” property of the setting

### nm_setting_wireless_get_powersave ()

    guint32
    nm_setting_wireless_get_powersave (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “powersave” property of the setting

Since: 1.2

### nm_setting_wireless_get_mac_address_randomization ()

    NMSettingMacRandomization
    nm_setting_wireless_get_mac_address_randomization
                                   (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “mac-address-randomization” property of the setting

Since: 1.2

### nm_setting_wireless_add_seen_bssid ()

    gboolean
    nm_setting_wireless_add_seen_bssid (NMSettingWireless *setting,
                                        const char *bssid);

Adds a new Wi-Fi AP's BSSID to the previously seen BSSID list of the setting. NetworkManager now tracks previously seen BSSIDs internally so this function no longer has much use. Actually, changes you make using this function will not be preserved.

#### Parameters

setting | the NMSettingWireless |
bssid | the new BSSID to add to the list |

#### Returns

`TRUE` if `bssid` was already known, `FALSE` if not

### nm_setting_wireless_get_num_seen_bssids ()

    guint32
    nm_setting_wireless_get_num_seen_bssids
                                   (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the number of BSSIDs in the previously seen BSSID list

### nm_setting_wireless_get_seen_bssid ()

    const char *
    nm_setting_wireless_get_seen_bssid (NMSettingWireless *setting,
                                        guint32 i);

#### Parameters

setting | the NMSettingWireless |
i | index of a BSSID in the previously seen BSSID list |

#### Returns

the BSSID at index `i`

### nm_setting_wireless_ap_security_compatible ()

    gboolean
    nm_setting_wireless_ap_security_compatible
                                   (NMSettingWireless *s_wireless,
                                    NMSettingWirelessSecurity *s_wireless_sec,
                                    NM80211ApFlags ap_flags,
                                    NM80211ApSecurityFlags ap_wpa,
                                    NM80211ApSecurityFlags ap_rsn,
                                    NM80211Mode ap_mode);

Given a NMSettingWireless and an optional NMSettingWirelessSecurity, determine if the configuration given by the settings is compatible with the security of an access point using that access point's capability flags and mode. Useful for clients that wish to filter a set of connections against a set of access points and determine which connections are compatible with which access points.

#### Parameters

s_wireless | a NMSettingWireless |
s_wireless_sec | a NMSettingWirelessSecurity or `NULL` |
ap_flags | the `NM80211ApFlags` of the given access point |
ap_wpa | the `NM80211ApSecurityFlags` of the given access point's WPA capabilities |
ap_rsn | the `NM80211ApSecurityFlags` of the given access point's WPA2/RSN capabilities |
ap_mode | the 802.11 mode of the AP, either Ad-Hoc or Infrastructure |

#### Returns

`TRUE` if the given settings are compatible with the access point's security flags and mode, `FALSE` if they are not.

### nm_setting_wireless_get_wake_on_wlan ()

    NMSettingWirelessWakeOnWLan
    nm_setting_wireless_get_wake_on_wlan (NMSettingWireless *setting);

Returns the Wake-on-WLAN options enabled for the connection

#### Parameters

setting | the NMSettingWireless |

#### Returns

the Wake-on-WLAN options

Since: 1.12

### nm_setting_wireless_get_ap_isolation ()

    NMTernary
    nm_setting_wireless_get_ap_isolation (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “ap-isolation” property of the setting

Since: 1.28

## Types and Values

### NM_SETTING_WIRELESS_SETTING_NAME

    #define NM_SETTING_WIRELESS_SETTING_NAME "802-11-wireless"

### enum NMSettingWirelessWakeOnWLan

Options for “wake-on-wlan”. Note that not all options are supported by all devices.

#### Members

NM_SETTING_WIRELESS_WAKE_ON_WLAN_NONE | Wake-on-WLAN disabled |
NM_SETTING_WIRELESS_WAKE_ON_WLAN_ANY | Wake on any activity |
NM_SETTING_WIRELESS_WAKE_ON_WLAN_DISCONNECT | Wake on disconnect |
NM_SETTING_WIRELESS_WAKE_ON_WLAN_MAGIC | Wake on magic packet |
NM_SETTING_WIRELESS_WAKE_ON_WLAN_GTK_REKEY_FAILURE | Wake on GTK rekey failure |
NM_SETTING_WIRELESS_WAKE_ON_WLAN_EAP_IDENTITY_REQUEST | Wake on EAP identity request |
NM_SETTING_WIRELESS_WAKE_ON_WLAN_4WAY_HANDSHAKE | Wake on 4way handshake |
NM_SETTING_WIRELESS_WAKE_ON_WLAN_RFKILL_RELEASE | Wake on rfkill release |
NM_SETTING_WIRELESS_WAKE_ON_WLAN_TCP |  |
NM_SETTING_WIRELESS_WAKE_ON_WLAN_ALL | Wake on all events. This does not include the exclusive flags `NM_SETTING_WIRELESS_WAKE_ON_WLAN_DEFAULT` or `NM_SETTING_WIRELESS_WAKE_ON_WLAN_IGNORE` . |
NM_SETTING_WIRELESS_WAKE_ON_WLAN_DEFAULT | Use the default value |
NM_SETTING_WIRELESS_WAKE_ON_WLAN_IGNORE | Don't change configured settings |
NM_SETTING_WIRELESS_WAKE_ON_WLAN_EXCLUSIVE_FLAGS | Mask of flags that are incompatible with other flags |

Since: 1.12

### NM_SETTING_WIRELESS_SSID

    #define NM_SETTING_WIRELESS_SSID                      "ssid"

### NM_SETTING_WIRELESS_MODE

    #define NM_SETTING_WIRELESS_MODE                      "mode"

### NM_SETTING_WIRELESS_BAND

    #define NM_SETTING_WIRELESS_BAND                      "band"

### NM_SETTING_WIRELESS_CHANNEL

    #define NM_SETTING_WIRELESS_CHANNEL                   "channel"

### NM_SETTING_WIRELESS_BSSID

    #define NM_SETTING_WIRELESS_BSSID                     "bssid"

### NM_SETTING_WIRELESS_RATE

    #define NM_SETTING_WIRELESS_RATE                      "rate"

### NM_SETTING_WIRELESS_TX_POWER

    #define NM_SETTING_WIRELESS_TX_POWER                  "tx-power"

### NM_SETTING_WIRELESS_MAC_ADDRESS

    #define NM_SETTING_WIRELESS_MAC_ADDRESS               "mac-address"

### NM_SETTING_WIRELESS_CLONED_MAC_ADDRESS

    #define NM_SETTING_WIRELESS_CLONED_MAC_ADDRESS        "cloned-mac-address"

### NM_SETTING_WIRELESS_GENERATE_MAC_ADDRESS_MASK

    #define NM_SETTING_WIRELESS_GENERATE_MAC_ADDRESS_MASK "generate-mac-address-mask"

### NM_SETTING_WIRELESS_MAC_ADDRESS_BLACKLIST

    #define NM_SETTING_WIRELESS_MAC_ADDRESS_BLACKLIST     "mac-address-blacklist"

### NM_SETTING_WIRELESS_MTU

    #define NM_SETTING_WIRELESS_MTU                       "mtu"

### NM_SETTING_WIRELESS_SEEN_BSSIDS

    #define NM_SETTING_WIRELESS_SEEN_BSSIDS               "seen-bssids"

### NM_SETTING_WIRELESS_HIDDEN

    #define NM_SETTING_WIRELESS_HIDDEN                    "hidden"

### NM_SETTING_WIRELESS_POWERSAVE

    #define NM_SETTING_WIRELESS_POWERSAVE                 "powersave"

### NM_SETTING_WIRELESS_MAC_ADDRESS_RANDOMIZATION

    #define NM_SETTING_WIRELESS_MAC_ADDRESS_RANDOMIZATION "mac-address-randomization"

### NM_SETTING_WIRELESS_WAKE_ON_WLAN

    #define NM_SETTING_WIRELESS_WAKE_ON_WLAN              "wake-on-wlan"

### NM_SETTING_WIRELESS_AP_ISOLATION

    #define NM_SETTING_WIRELESS_AP_ISOLATION              "ap-isolation"

### NM_SETTING_WIRELESS_MODE_ADHOC

    #define NM_SETTING_WIRELESS_MODE_ADHOC "adhoc"

Indicates Ad-Hoc mode where no access point is expected to be present.

### NM_SETTING_WIRELESS_MODE_AP

    #define NM_SETTING_WIRELESS_MODE_AP "ap"

Indicates AP/master mode where the wireless device is started as an access point/hotspot.

### NM_SETTING_WIRELESS_MODE_INFRA

    #define NM_SETTING_WIRELESS_MODE_INFRA "infrastructure"

Indicates infrastructure mode where an access point is expected to be present for this connection.

### NM_SETTING_WIRELESS_MODE_MESH

    #define NM_SETTING_WIRELESS_MODE_MESH "mesh"

Indicates that the connection should create a mesh point.

Since: 1.20

### enum NMSettingWirelessPowersave

These flags indicate whether wireless powersave must be enabled.

#### Members

NM_SETTING_WIRELESS_POWERSAVE_DEFAULT | use the default value |
NM_SETTING_WIRELESS_POWERSAVE_IGNORE | don't touch existing setting |
NM_SETTING_WIRELESS_POWERSAVE_DISABLE | disable powersave |
NM_SETTING_WIRELESS_POWERSAVE_ENABLE | enable powersave |
_NM_SETTING_WIRELESS_POWERSAVE_NUM |  |
NM_SETTING_WIRELESS_POWERSAVE_LAST |  |

Since: 1.2