## NMSettingWireless

NMSettingWireless — Describes connection properties for 802.11 Wi-Fi networks

## Functions

GQuark | nm_setting_wireless_error_quark ()
NMSetting * | nm_setting_wireless_new ()
const GByteArray * | 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 GByteArray * | nm_setting_wireless_get_bssid ()
guint32 | nm_setting_wireless_get_rate ()
guint32 | nm_setting_wireless_get_tx_power ()
const GByteArray * | nm_setting_wireless_get_mac_address ()
const GByteArray * | nm_setting_wireless_get_cloned_mac_address ()
const GSList * | 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 ()
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 ()
const char * | nm_setting_wireless_get_security ()

## Properties

gchar * | band | Read / Write
GArray_guchar_ * | bssid | Read / Write
guint | channel | Read / Write / Construct
GArray_guchar_ * | cloned-mac-address | Read / Write
gboolean | hidden | Read / Write
GArray_guchar_ * | mac-address | Read / Write
GSList_gchararray_ * | mac-address-blacklist | Read / Write
gchar * | mode | Read / Write
guint | mtu | Read / Write / Construct
guint | powersave | Read / Write
guint | rate | Read / Write / Construct
gchar * | security | Read / Write
GSList_gchararray_ * | seen-bssids | Read / Write
GArray_guchar_ * | ssid | Read / Write
guint | tx-power | Read / Write / Construct

## Types and Values

#define | NM_SETTING_WIRELESS_SETTING_NAME
enum | NMSettingWirelessError
#define | NM_SETTING_WIRELESS_ERROR
#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_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_SEC
#define | NM_SETTING_WIRELESS_MODE_ADHOC
#define | NM_SETTING_WIRELESS_MODE_AP
#define | NM_SETTING_WIRELESS_MODE_INFRA

## Object Hierarchy

        GEnum
        ╰── NMSettingWirelessError
        GObject
        ╰── NMSetting
            ╰── NMSettingWireless

## Includes

    #include <nm-setting-wireless.h>

## Description

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

## Functions

### nm_setting_wireless_error_quark ()

    GQuark
    nm_setting_wireless_error_quark (void);

Registers an error quark for NMSettingWireless if necessary.

#### Returns

the error quark used for NMSettingWireless errors.

### 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 ()

    const GByteArray *
    nm_setting_wireless_get_ssid (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “ssid” property of the setting

### 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 GByteArray *
    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 GByteArray *
    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 GByteArray *
    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_mac_address_blacklist ()

    const GSList *
    nm_setting_wireless_get_mac_address_blacklist
                                   (NMSettingWireless *setting);

#### Parameters

setting | the NMSettingWireless |

#### Returns

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

[element-type GLib.ByteArray]

### 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

Since: 0.9.10

### 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`

Since: 0.9.10

### 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

Since: 0.9.10

### 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 |

Since: 0.9.10

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

Since: 0.9.10

### 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 |

Since: 0.9.10

### 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_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_security ()

    const char *
    nm_setting_wireless_get_security (NMSettingWireless *setting);

`nm_setting_wireless_get_security` has been deprecated since version 0.9.10 and should not be used in newly-written code.

No longer used. Security rescrictions are recognized by the presence of NM_SETTING_WIRELESS_SECURITY_SETTING_NAME in the connection.

#### Parameters

setting | the NMSettingWireless |

#### Returns

the “security” property of the setting

## Types and Values

### NM_SETTING_WIRELESS_SETTING_NAME

    #define NM_SETTING_WIRELESS_SETTING_NAME "802-11-wireless"

### enum NMSettingWirelessError

#### Members

NM_SETTING_WIRELESS_ERROR_UNKNOWN | unknown or unclassified error |
NM_SETTING_WIRELESS_ERROR_INVALID_PROPERTY | the property was invalid |
NM_SETTING_WIRELESS_ERROR_MISSING_PROPERTY | the property was missing and is required |
NM_SETTING_WIRELESS_ERROR_MISSING_SECURITY_SETTING | property values require the presence of an NMSettingWirelessSecurity object in the connection |
NM_SETTING_WIRELESS_ERROR_CHANNEL_REQUIRES_BAND | the property channel was set to a value that requires the “band” property to be set |

### NM_SETTING_WIRELESS_ERROR

    #define NM_SETTING_WIRELESS_ERROR nm_setting_wireless_error_quark ()

### 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_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_SEC

    #define NM_SETTING_WIRELESS_SEC         "security"

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

Since: 0.9.8

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

## Property Details

### The `“band”` property

      “band”                     gchar *

802.11 frequency band of the network. One of "a" for 5GHz 802.11a or "bg" for 2.4GHz 802.11. This will lock associations to the Wi-Fi network to the specific band, i.e. if "a" is specified, the device will not associate with the same network in the 2.4GHz band even if the network's settings are compatible. This setting depends on specific driver capability and may not work with all drivers.

Flags: Read / Write

Default value: NULL

### The `“bssid”` property

      “bssid”                    GArray_guchar_ *

If specified, directs the device to only associate with the given access point. This capability is highly driver dependent and not supported by all devices. Note: this property does not control the BSSID used when creating an Ad-Hoc network and is unlikely to in the future.

Flags: Read / Write

### The `“channel”` property

      “channel”                  guint

Wireless channel to use for the Wi-Fi connection. The device will only join (or create for Ad-Hoc networks) a Wi-Fi network on the specified channel. Because channel numbers overlap between bands, this property also requires the "band" property to be set.

Flags: Read / Write / Construct

Default value: 0

### The `“cloned-mac-address”` property

      “cloned-mac-address”       GArray_guchar_ *

If specified, request that the Wi-Fi device use this MAC address instead of its permanent MAC address. This is known as MAC cloning or spoofing.

Flags: Read / Write

### The `“hidden”` property

      “hidden”                   gboolean

If `TRUE`, indicates this network is a non-broadcasting network that hides its SSID. In this case various workarounds may take place, such as probe-scanning the SSID for more reliable network discovery. However, these workarounds expose inherent insecurities with hidden SSID networks, and thus hidden SSID networks should be used with caution.

Flags: Read / Write

Default value: FALSE

### The `“mac-address”` property

      “mac-address”              GArray_guchar_ *

If specified, this connection will only apply to the Wi-Fi device whose permanent MAC address matches. This property does not change the MAC address of the device (i.e. MAC spoofing).

Flags: Read / Write

### The `“mac-address-blacklist”` property

      “mac-address-blacklist”    GSList_gchararray_ *

A list of permanent MAC addresses of Wi-Fi devices to which this connection should never apply. Each MAC address should be given in the standard hex-digits-and-colons notation (eg "00:11:22:33:44:55").

Flags: Read / Write

### The `“mode”` property

      “mode”                     gchar *

Wi-Fi network mode; one of "infrastructure", "adhoc" or "ap". If blank, infrastructure is assumed.

Flags: Read / Write

Default value: NULL

### The `“mtu”` property

      “mtu”                      guint

If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple Ethernet frames.

Flags: Read / Write / Construct

Default value: 0

### The `“powersave”` property

      “powersave”                guint

If set to `FALSE`, Wi-Fi power saving behavior is disabled. If set to `TRUE`, Wi-Fi power saving behavior is enabled. All other values are reserved. Note that even though only boolean values are allowed, the property type is an unsigned integer to allow for future expansion.

Flags: Read / Write

Default value: 0

Since: 1.2

### The `“rate”` property

      “rate”                     guint

If non-zero, directs the device to only use the specified bitrate for communication with the access point. Units are in Kb/s, ie 5500 = 5.5 Mbit/s. This property is highly driver dependent and not all devices support setting a static bitrate.

Flags: Read / Write / Construct

Default value: 0

### The `“security”` property

      “security”                 gchar *

If the wireless connection has any security restrictions, like 802.1x, WEP, or WPA, set this property to `NM_SETTING_WIRELESS_SECURITY_SETTING_NAME` and ensure the connection contains a valid NMSettingWirelessSecurity setting.

`NMSettingWireless:security` has been deprecated since version 0.9.10 and should not be used in newly-written code.

No longer used. Security restrictions are recognized by the presence of a NMSettingWirelessSecurity setting in the connection.

Flags: Read / Write

Default value: NULL

### The `“seen-bssids”` property

      “seen-bssids”              GSList_gchararray_ *

A list of BSSIDs (each BSSID formatted as a MAC address like "00:11:22:33:44:55") that have been detected as part of the Wi-Fi network. NetworkManager internally tracks previously seen BSSIDs. The property is only meant for reading and reflects the BSSID list of NetworkManager. The changes you make to this property will not be preserved.

Flags: Read / Write

### The `“ssid”` property

      “ssid”                     GArray_guchar_ *

SSID of the Wi-Fi network. Must be specified.

Flags: Read / Write

### The `“tx-power”` property

      “tx-power”                 guint

If non-zero, directs the device to use the specified transmit power. Units are dBm. This property is highly driver dependent and not all devices support setting a static transmit power.

Flags: Read / Write / Construct

Default value: 0