mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager.git
synced 2026-02-05 20:30:35 +01:00
docs: update Wireless setting documentation
This commit is contained in:
Dan Williams
parent
853b6f117f
commit
d0187fbbc6
2 changed files with 171 additions and 17 deletions
|
|
@ -37,6 +37,22 @@
|
|||
#include "nm-dbus-glib-types.h"
|
||||
#include "nm-utils-private.h"
|
||||
|
||||
/**
|
||||
* SECTION:nm-setting-wireless
|
||||
* @short_description: Describes connection properties for 802.11 WiFi networks
|
||||
* @include: nm-setting-wireless.h
|
||||
*
|
||||
* The #NMSettingWireless object is a #NMSetting subclass that describes properties
|
||||
* necessary for connection to 802.11 WiFi networks.
|
||||
**/
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_error_quark:
|
||||
*
|
||||
* Registers an error quark for #NMSettingWireless if necessary.
|
||||
*
|
||||
* Returns: the error quark used for #NMSettingWireless errors.
|
||||
**/
|
||||
GQuark
|
||||
nm_setting_wireless_error_quark (void)
|
||||
{
|
||||
|
|
@ -130,6 +146,27 @@ match_cipher (const char *cipher,
|
|||
return TRUE;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_ap_security_compatible:
|
||||
* @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
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* Returns: %TRUE if the given settings are compatible with the access point's
|
||||
* security flags and mode, %FALSE if they are not.
|
||||
*/
|
||||
gboolean
|
||||
nm_setting_wireless_ap_security_compatible (NMSettingWireless *s_wireless,
|
||||
NMSettingWirelessSecurity *s_wireless_sec,
|
||||
|
|
@ -291,12 +328,25 @@ nm_setting_wireless_ap_security_compatible (NMSettingWireless *s_wireless,
|
|||
return FALSE;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_new:
|
||||
*
|
||||
* Creates a new #NMSettingWireless object with default values.
|
||||
*
|
||||
* Returns: the new empty #NMSettingWireless object
|
||||
**/
|
||||
NMSetting *
|
||||
nm_setting_wireless_new (void)
|
||||
{
|
||||
return (NMSetting *) g_object_new (NM_TYPE_SETTING_WIRELESS, NULL);
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_ssid:
|
||||
* @setting: the #NMSettingWireless
|
||||
*
|
||||
* Returns: the #NMSettingWireless:ssid property of the setting
|
||||
**/
|
||||
const GByteArray *
|
||||
nm_setting_wireless_get_ssid (NMSettingWireless *setting)
|
||||
{
|
||||
|
|
@ -305,6 +355,12 @@ nm_setting_wireless_get_ssid (NMSettingWireless *setting)
|
|||
return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->ssid;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_mode:
|
||||
* @setting: the #NMSettingWireless
|
||||
*
|
||||
* Returns: the #NMSettingWireless:mode property of the setting
|
||||
**/
|
||||
const char *
|
||||
nm_setting_wireless_get_mode (NMSettingWireless *setting)
|
||||
{
|
||||
|
|
@ -313,6 +369,12 @@ nm_setting_wireless_get_mode (NMSettingWireless *setting)
|
|||
return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->mode;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_band:
|
||||
* @setting: the #NMSettingWireless
|
||||
*
|
||||
* Returns: the #NMSettingWireless:band property of the setting
|
||||
**/
|
||||
const char *
|
||||
nm_setting_wireless_get_band (NMSettingWireless *setting)
|
||||
{
|
||||
|
|
@ -321,6 +383,12 @@ nm_setting_wireless_get_band (NMSettingWireless *setting)
|
|||
return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->band;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_channel:
|
||||
* @setting: the #NMSettingWireless
|
||||
*
|
||||
* Returns: the #NMSettingWireless:channel property of the setting
|
||||
**/
|
||||
guint32
|
||||
nm_setting_wireless_get_channel (NMSettingWireless *setting)
|
||||
{
|
||||
|
|
@ -329,6 +397,12 @@ nm_setting_wireless_get_channel (NMSettingWireless *setting)
|
|||
return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->channel;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_bssid:
|
||||
* @setting: the #NMSettingWireless
|
||||
*
|
||||
* Returns: the #NMSettingWireless:bssid property of the setting
|
||||
**/
|
||||
const GByteArray *
|
||||
nm_setting_wireless_get_bssid (NMSettingWireless *setting)
|
||||
{
|
||||
|
|
@ -337,6 +411,12 @@ nm_setting_wireless_get_bssid (NMSettingWireless *setting)
|
|||
return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->bssid;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_rate:
|
||||
* @setting: the #NMSettingWireless
|
||||
*
|
||||
* Returns: the #NMSettingWireless:rate property of the setting
|
||||
**/
|
||||
guint32
|
||||
nm_setting_wireless_get_rate (NMSettingWireless *setting)
|
||||
{
|
||||
|
|
@ -345,6 +425,12 @@ nm_setting_wireless_get_rate (NMSettingWireless *setting)
|
|||
return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->rate;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_tx_power:
|
||||
* @setting: the #NMSettingWireless
|
||||
*
|
||||
* Returns: the #NMSettingWireless:tx-power property of the setting
|
||||
**/
|
||||
guint32
|
||||
nm_setting_wireless_get_tx_power (NMSettingWireless *setting)
|
||||
{
|
||||
|
|
@ -353,6 +439,12 @@ nm_setting_wireless_get_tx_power (NMSettingWireless *setting)
|
|||
return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->tx_power;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_mac_address:
|
||||
* @setting: the #NMSettingWireless
|
||||
*
|
||||
* Returns: the #NMSettingWireless:mac-address property of the setting
|
||||
**/
|
||||
const GByteArray *
|
||||
nm_setting_wireless_get_mac_address (NMSettingWireless *setting)
|
||||
{
|
||||
|
|
@ -361,6 +453,12 @@ nm_setting_wireless_get_mac_address (NMSettingWireless *setting)
|
|||
return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->device_mac_address;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_cloned_mac_address:
|
||||
* @setting: the #NMSettingWireless
|
||||
*
|
||||
* Returns: the #NMSettingWireless:cloned-mac-address property of the setting
|
||||
**/
|
||||
const GByteArray *
|
||||
nm_setting_wireless_get_cloned_mac_address (NMSettingWireless *setting)
|
||||
{
|
||||
|
|
@ -369,6 +467,13 @@ nm_setting_wireless_get_cloned_mac_address (NMSettingWireless *setting)
|
|||
return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->cloned_mac_address;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_mac_address_blacklist:
|
||||
* @setting: the #NMSettingWireless
|
||||
*
|
||||
* Returns: (element-type GLib.ByteArray): the
|
||||
* #NMSettingWireless:mac-address-blacklist property of the setting
|
||||
**/
|
||||
const GSList *
|
||||
nm_setting_wireless_get_mac_address_blacklist (NMSettingWireless *setting)
|
||||
{
|
||||
|
|
@ -377,6 +482,12 @@ nm_setting_wireless_get_mac_address_blacklist (NMSettingWireless *setting)
|
|||
return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->mac_address_blacklist;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_mtu:
|
||||
* @setting: the #NMSettingWireless
|
||||
*
|
||||
* Returns: the #NMSettingWireless:mtu property of the setting
|
||||
**/
|
||||
guint32
|
||||
nm_setting_wireless_get_mtu (NMSettingWireless *setting)
|
||||
{
|
||||
|
|
@ -385,6 +496,12 @@ nm_setting_wireless_get_mtu (NMSettingWireless *setting)
|
|||
return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->mtu;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_security:
|
||||
* @setting: the #NMSettingWireless
|
||||
*
|
||||
* Returns: the #NMSettingWireless:security property of the setting
|
||||
**/
|
||||
const char *
|
||||
nm_setting_wireless_get_security (NMSettingWireless *setting)
|
||||
{
|
||||
|
|
@ -393,6 +510,17 @@ nm_setting_wireless_get_security (NMSettingWireless *setting)
|
|||
return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->security;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_add_seen_bssid:
|
||||
* @setting: the #NMSettingWireless
|
||||
* @bssid: the new BSSID to add to the list
|
||||
*
|
||||
* Adds a new WiFi AP's BSSID to the previously seen BSSID list of the setting.
|
||||
* NetworkManager tracks previously seen BSSIDs internally so this function
|
||||
* no longer has much use.
|
||||
*
|
||||
* Returns: %TRUE if @bssid was already known, %FALSE if not
|
||||
**/
|
||||
gboolean
|
||||
nm_setting_wireless_add_seen_bssid (NMSettingWireless *setting,
|
||||
const char *bssid)
|
||||
|
|
@ -426,6 +554,12 @@ nm_setting_wireless_add_seen_bssid (NMSettingWireless *setting,
|
|||
return !found;
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_num_seen_bssids:
|
||||
* @setting: the #NMSettingWireless
|
||||
*
|
||||
* Returns: the number of BSSIDs in the previously seen BSSID list
|
||||
**/
|
||||
guint32
|
||||
nm_setting_wireless_get_num_seen_bssids (NMSettingWireless *setting)
|
||||
{
|
||||
|
|
@ -434,6 +568,13 @@ nm_setting_wireless_get_num_seen_bssids (NMSettingWireless *setting)
|
|||
return g_slist_length (NM_SETTING_WIRELESS_GET_PRIVATE (setting)->seen_bssids);
|
||||
}
|
||||
|
||||
/**
|
||||
* nm_setting_wireless_get_seen_bssid:
|
||||
* @setting: the #NMSettingWireless
|
||||
* @i: index of a BSSID in the previously seen BSSID list
|
||||
*
|
||||
* Returns: the BSSID at index @i
|
||||
**/
|
||||
const char *
|
||||
nm_setting_wireless_get_seen_bssid (NMSettingWireless *setting,
|
||||
guint32 i)
|
||||
|
|
@ -921,27 +1062,18 @@ nm_setting_wireless_class_init (NMSettingWirelessClass *setting_class)
|
|||
*
|
||||
* 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 WiFI network.
|
||||
* The settings service will usually populate this property by periodically
|
||||
* asking NetworkManager what the device's current AP is while connected
|
||||
* to the network (or monitoring the device's 'active-ap' property) and
|
||||
* adding the current AP'sBSSID to this list. This list helps NetworkManager
|
||||
* find hidden APs by matching up scan results with the BSSIDs in this list.
|
||||
* NetworkManager internally tracks previously seen BSSIDs so this property
|
||||
* is no longer of much use.
|
||||
**/
|
||||
g_object_class_install_property
|
||||
(object_class, PROP_SEEN_BSSIDS,
|
||||
_nm_param_spec_specialized (NM_SETTING_WIRELESS_SEEN_BSSIDS,
|
||||
"Seen BSSIDS",
|
||||
"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 WiFI network. The "
|
||||
"settings service will usually populate this "
|
||||
"property by periodically asking NetworkManager "
|
||||
"what the device's current AP is while connected "
|
||||
"to the network (or monitoring the device's "
|
||||
"'active-ap' property) and adding the current AP's "
|
||||
"BSSID to this list. This list helps NetworkManager "
|
||||
"find hidden APs by matching up scan results with "
|
||||
"the BSSIDs in this list.",
|
||||
"address like 00:11:22:33:44:55') that have been "
|
||||
"detected as part of the WiFI network. "
|
||||
"NetworkManager internally tracks previously seen "
|
||||
"BSSIDs so this property is no longer of much use.",
|
||||
DBUS_TYPE_G_LIST_OF_STRING,
|
||||
G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE));
|
||||
|
||||
|
|
|
|||
|
|
@ -41,8 +41,18 @@ G_BEGIN_DECLS
|
|||
|
||||
#define NM_SETTING_WIRELESS_SETTING_NAME "802-11-wireless"
|
||||
|
||||
typedef enum
|
||||
{
|
||||
/**
|
||||
* 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 #NMSettingWireless:band property to be set
|
||||
*/
|
||||
typedef enum {
|
||||
NM_SETTING_WIRELESS_ERROR_UNKNOWN = 0,
|
||||
NM_SETTING_WIRELESS_ERROR_INVALID_PROPERTY,
|
||||
NM_SETTING_WIRELESS_ERROR_MISSING_PROPERTY,
|
||||
|
|
@ -70,7 +80,19 @@ GQuark nm_setting_wireless_error_quark (void);
|
|||
#define NM_SETTING_WIRELESS_SEEN_BSSIDS "seen-bssids"
|
||||
#define NM_SETTING_WIRELESS_SEC "security"
|
||||
|
||||
/**
|
||||
* NM_SETTING_WIRELESS_MODE_ADHOC:
|
||||
*
|
||||
* Indicates Ad-Hoc mode where no access point is expected to be present.
|
||||
*/
|
||||
#define NM_SETTING_WIRELESS_MODE_ADHOC "adhoc"
|
||||
|
||||
/**
|
||||
* NM_SETTING_WIRELESS_MODE_INFRA
|
||||
*
|
||||
* Indicates infrastructure mode where an access point is expected to be present
|
||||
* for this connection.
|
||||
*/
|
||||
#define NM_SETTING_WIRELESS_MODE_INFRA "infrastructure"
|
||||
|
||||
typedef struct {
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue