NMSettingWireless

NMSettingWireless — Describes connection properties for 802.11 WiFi networks

Synopsis

#include <nm-setting-wireless.h>

                    NMSettingWireless;
                    NMSettingWirelessClass;
enum                NMSettingWirelessError;
#define             NM_SETTING_WIRELESS_BAND
#define             NM_SETTING_WIRELESS_BSSID
#define             NM_SETTING_WIRELESS_CHANNEL
#define             NM_SETTING_WIRELESS_CLONED_MAC_ADDRESS
#define             NM_SETTING_WIRELESS_ERROR
#define             NM_SETTING_WIRELESS_HIDDEN
#define             NM_SETTING_WIRELESS_MAC_ADDRESS
#define             NM_SETTING_WIRELESS_MAC_ADDRESS_BLACKLIST
#define             NM_SETTING_WIRELESS_MODE
#define             NM_SETTING_WIRELESS_MODE_ADHOC
#define             NM_SETTING_WIRELESS_MODE_AP
#define             NM_SETTING_WIRELESS_MODE_INFRA
#define             NM_SETTING_WIRELESS_MTU
#define             NM_SETTING_WIRELESS_RATE
#define             NM_SETTING_WIRELESS_SEC
#define             NM_SETTING_WIRELESS_SEEN_BSSIDS
#define             NM_SETTING_WIRELESS_SETTING_NAME
#define             NM_SETTING_WIRELESS_SSID
#define             NM_SETTING_WIRELESS_TX_POWER
gboolean            nm_setting_wireless_add_seen_bssid  (NMSettingWireless *setting,
                                                         const char *bssid);
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);
GQuark              nm_setting_wireless_error_quark     (void);
const char *        nm_setting_wireless_get_band        (NMSettingWireless *setting);
const GByteArray *  nm_setting_wireless_get_bssid       (NMSettingWireless *setting);
guint32             nm_setting_wireless_get_channel     (NMSettingWireless *setting);
const GByteArray *  nm_setting_wireless_get_cloned_mac_address
                                                        (NMSettingWireless *setting);
gboolean            nm_setting_wireless_get_hidden      (NMSettingWireless *setting);
const GByteArray *  nm_setting_wireless_get_mac_address (NMSettingWireless *setting);
const GSList *      nm_setting_wireless_get_mac_address_blacklist
                                                        (NMSettingWireless *setting);
const char *        nm_setting_wireless_get_mode        (NMSettingWireless *setting);
guint32             nm_setting_wireless_get_mtu         (NMSettingWireless *setting);
guint32             nm_setting_wireless_get_num_seen_bssids
                                                        (NMSettingWireless *setting);
guint32             nm_setting_wireless_get_rate        (NMSettingWireless *setting);
const char *        nm_setting_wireless_get_security    (NMSettingWireless *setting);
const char *        nm_setting_wireless_get_seen_bssid  (NMSettingWireless *setting,
                                                         guint32 i);
const GByteArray *  nm_setting_wireless_get_ssid        (NMSettingWireless *setting);
guint32             nm_setting_wireless_get_tx_power    (NMSettingWireless *setting);
NMSetting *         nm_setting_wireless_new             (void);

Object Hierarchy

  GObject
   +----NMSetting
         +----NMSettingWireless
  GEnum
   +----NMSettingWirelessError

Properties

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

Description

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

Details

NMSettingWireless

typedef struct _NMSettingWireless NMSettingWireless;


NMSettingWirelessClass

typedef struct {
	NMSettingClass parent;

	/* Padding for future expansion */
	void (*_reserved1) (void);
	void (*_reserved2) (void);
	void (*_reserved3) (void);
	void (*_reserved4) (void);
} NMSettingWirelessClass;


enum NMSettingWirelessError

typedef enum {
	NM_SETTING_WIRELESS_ERROR_UNKNOWN = 0,              /*< nick=UnknownError >*/
	NM_SETTING_WIRELESS_ERROR_INVALID_PROPERTY,         /*< nick=InvalidProperty >*/
	NM_SETTING_WIRELESS_ERROR_MISSING_PROPERTY,         /*< nick=MissingProperty >*/
	NM_SETTING_WIRELESS_ERROR_MISSING_SECURITY_SETTING, /*< nick=MissingSecuritySetting >*/
	NM_SETTING_WIRELESS_ERROR_CHANNEL_REQUIRES_BAND     /*< nick=ChannelRequiresBand >*/
} NMSettingWirelessError;

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_BAND

#define NM_SETTING_WIRELESS_BAND        "band"


NM_SETTING_WIRELESS_BSSID

#define NM_SETTING_WIRELESS_BSSID       "bssid"


NM_SETTING_WIRELESS_CHANNEL

#define NM_SETTING_WIRELESS_CHANNEL     "channel"


NM_SETTING_WIRELESS_CLONED_MAC_ADDRESS

#define NM_SETTING_WIRELESS_CLONED_MAC_ADDRESS "cloned-mac-address"


NM_SETTING_WIRELESS_ERROR

#define NM_SETTING_WIRELESS_ERROR nm_setting_wireless_error_quark ()


NM_SETTING_WIRELESS_HIDDEN

#define NM_SETTING_WIRELESS_HIDDEN      "hidden"


NM_SETTING_WIRELESS_MAC_ADDRESS

#define NM_SETTING_WIRELESS_MAC_ADDRESS "mac-address"


NM_SETTING_WIRELESS_MAC_ADDRESS_BLACKLIST

#define NM_SETTING_WIRELESS_MAC_ADDRESS_BLACKLIST "mac-address-blacklist"


NM_SETTING_WIRELESS_MODE

#define NM_SETTING_WIRELESS_MODE        "mode"


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.


NM_SETTING_WIRELESS_MTU

#define NM_SETTING_WIRELESS_MTU         "mtu"


NM_SETTING_WIRELESS_RATE

#define NM_SETTING_WIRELESS_RATE        "rate"


NM_SETTING_WIRELESS_SEC

#define NM_SETTING_WIRELESS_SEC         "security"


NM_SETTING_WIRELESS_SEEN_BSSIDS

#define NM_SETTING_WIRELESS_SEEN_BSSIDS "seen-bssids"


NM_SETTING_WIRELESS_SETTING_NAME

#define NM_SETTING_WIRELESS_SETTING_NAME "802-11-wireless"


NM_SETTING_WIRELESS_SSID

#define NM_SETTING_WIRELESS_SSID        "ssid"


NM_SETTING_WIRELESS_TX_POWER

#define NM_SETTING_WIRELESS_TX_POWER    "tx-power"


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.

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

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_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_get_band ()

const char *        nm_setting_wireless_get_band        (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the "band" property of the setting

nm_setting_wireless_get_bssid ()

const GByteArray *  nm_setting_wireless_get_bssid       (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the "bssid" property of the setting

nm_setting_wireless_get_channel ()

guint32             nm_setting_wireless_get_channel     (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the "channel" property of the setting

nm_setting_wireless_get_cloned_mac_address ()

const GByteArray *  nm_setting_wireless_get_cloned_mac_address
                                                        (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the "cloned-mac-address" property of the setting

nm_setting_wireless_get_hidden ()

gboolean            nm_setting_wireless_get_hidden      (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the "hidden" property of the setting

nm_setting_wireless_get_mac_address ()

const GByteArray *  nm_setting_wireless_get_mac_address (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the "mac-address" property of the setting

nm_setting_wireless_get_mac_address_blacklist ()

const GSList *      nm_setting_wireless_get_mac_address_blacklist
                                                        (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the "mac-address-blacklist" property of the setting. [element-type GLib.ByteArray]

nm_setting_wireless_get_mode ()

const char *        nm_setting_wireless_get_mode        (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the "mode" property of the setting

nm_setting_wireless_get_mtu ()

guint32             nm_setting_wireless_get_mtu         (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the "mtu" property of the setting

nm_setting_wireless_get_num_seen_bssids ()

guint32             nm_setting_wireless_get_num_seen_bssids
                                                        (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the number of BSSIDs in the previously seen BSSID list

nm_setting_wireless_get_rate ()

guint32             nm_setting_wireless_get_rate        (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the "rate" property of the setting

nm_setting_wireless_get_security ()

const char *        nm_setting_wireless_get_security    (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the "security" property of the setting

nm_setting_wireless_get_seen_bssid ()

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

setting :

the NMSettingWireless

i :

index of a BSSID in the previously seen BSSID list

Returns :

the BSSID at index i

nm_setting_wireless_get_ssid ()

const GByteArray *  nm_setting_wireless_get_ssid        (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the "ssid" property of the setting

nm_setting_wireless_get_tx_power ()

guint32             nm_setting_wireless_get_tx_power    (NMSettingWireless *setting);

setting :

the NMSettingWireless

Returns :

the "tx-power" property of the setting

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]

Property Details

The "band" property

  "band"                     gchar*                : Read / Write

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

Default value: NULL


The "bssid" property

  "bssid"                    GArray_guchar_*       : Read / Write

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.


The "channel" property

  "channel"                  guint                 : Read / Write / Construct

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

Default value: 0


The "cloned-mac-address" property

  "cloned-mac-address"       GArray_guchar_*       : Read / Write

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


The "hidden" property

  "hidden"                   gboolean              : Read / Write

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.

Default value: FALSE


The "mac-address" property

  "mac-address"              GArray_guchar_*       : Read / Write

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


The "mac-address-blacklist" property

  "mac-address-blacklist"    GSList_gchararray_*   : Read / Write

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


The "mode" property

  "mode"                     gchar*                : Read / Write

WiFi network mode; one of 'infrastructure', 'adhoc' or 'ap'. If blank, infrastructure is assumed.

Default value: NULL


The "mtu" property

  "mtu"                      guint                 : Read / Write / Construct

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

Default value: 0


The "rate" property

  "rate"                     guint                 : Read / Write / Construct

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.

Default value: 0


The "security" property

  "security"                 gchar*                : Read / Write

If the wireless connection has any security restrictions, like 802.1x, WEP, or WPA, set this property to '802-11-wireless-security' and ensure the connection contains a valid 802-11-wireless-security setting.

Default value: NULL


The "seen-bssids" property

  "seen-bssids"              GSList_gchararray_*   : Read / Write

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 BBSID list of NetworkManager. The changes you make to this property will not be preserved.


The "ssid" property

  "ssid"                     GArray_guchar_*       : Read / Write

SSID of the WiFi network.


The "tx-power" property

  "tx-power"                 guint                 : Read / Write / Construct

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.

Default value: 0