diff --git a/libnm-util/nm-setting-wireless.c b/libnm-util/nm-setting-wireless.c index 0daf859fef..9213429c84 100644 --- a/libnm-util/nm-setting-wireless.c +++ b/libnm-util/nm-setting-wireless.c @@ -693,91 +693,217 @@ nm_setting_wireless_class_init (NMSettingWirelessClass *setting_class) parent_class->verify = verify; /* Properties */ + /** + * NMSettingWireless:ssid: + * + * SSID of the WiFi network. + **/ g_object_class_install_property (object_class, PROP_SSID, _nm_param_spec_specialized (NM_SETTING_WIRELESS_SSID, "SSID", - "SSID", + "SSID of the WiFi network. Must be specified.", DBUS_TYPE_G_UCHAR_ARRAY, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingWireless:mode: + * + * WiFi network mode; one of 'infrastructure' or 'adhoc'. If blank, + * infrastructure is assumed. + **/ g_object_class_install_property (object_class, PROP_MODE, g_param_spec_string (NM_SETTING_WIRELESS_MODE, "Mode", - "Mode", + "WiFi network mode; one of 'infrastructure' or " + "'adhoc'. If blank, infrastructure is assumed.", NULL, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingWireless:band: + * + * 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. + **/ g_object_class_install_property (object_class, PROP_BAND, g_param_spec_string (NM_SETTING_WIRELESS_BAND, "Band", - "Band", + "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.", NULL, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingWireless:channel: + * + * 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. + **/ g_object_class_install_property (object_class, PROP_CHANNEL, g_param_spec_uint (NM_SETTING_WIRELESS_CHANNEL, "Channel", - "Channel", + "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.", 0, G_MAXUINT32, 0, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingWireless:bssid: + * + * 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. + **/ g_object_class_install_property (object_class, PROP_BSSID, _nm_param_spec_specialized (NM_SETTING_WIRELESS_BSSID, "BSSID", - "BSSID", + "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.", DBUS_TYPE_G_UCHAR_ARRAY, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingWireless:rate: + * + * 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. + **/ g_object_class_install_property (object_class, PROP_RATE, g_param_spec_uint (NM_SETTING_WIRELESS_RATE, "Rate", - "Rate", + "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.", 0, G_MAXUINT32, 0, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE)); + /** + * NMSettingWireless:tx-power: + * + * 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. + **/ g_object_class_install_property (object_class, PROP_TX_POWER, g_param_spec_uint (NM_SETTING_WIRELESS_TX_POWER, "TX Power", - "TX Power", + "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.", 0, G_MAXUINT32, 0, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE)); + /** + * NMSettingWireless:mac-address: + * + * If specified, this connection will only apply to the WiFi device + * whose MAC address matches. This property does not change the MAC address + * of the device (known as MAC spoofing). + **/ g_object_class_install_property (object_class, PROP_MAC_ADDRESS, _nm_param_spec_specialized (NM_SETTING_WIRELESS_MAC_ADDRESS, "MAC Address", - "Harware address", + "If specified, this connection will only apply to " + "the WiFi device whose MAC address matches. " + "This property does not change the MAC address " + "of the device (known as MAC spoofing).", DBUS_TYPE_G_UCHAR_ARRAY, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); + /** + * NMSettingWireless: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'sBSSID to this list. This list helps NetworkManager + * find hidden APs by matching up scan results with the BSSIDs in this list. + **/ g_object_class_install_property (object_class, PROP_SEEN_BSSIDS, _nm_param_spec_specialized (NM_SETTING_WIRELESS_SEEN_BSSIDS, "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.", DBUS_TYPE_G_LIST_OF_STRING, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE)); + /** + * NMSettingWireless:mtu: + * + * If non-zero, only transmit packets of the specified size or smaller, + * breaking larger packets up into multiple Ethernet frames. + **/ g_object_class_install_property (object_class, PROP_MTU, g_param_spec_uint (NM_SETTING_WIRELESS_MTU, "MTU", - "MTU", + "If non-zero, only transmit packets of the specified " + "size or smaller, breaking larger packets up into " + "multiple Ethernet frames.", 0, G_MAXUINT32, 0, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE)); + /** + * NMSettingWireless:security: + * + * 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. + **/ g_object_class_install_property (object_class, PROP_SEC, g_param_spec_string (NM_SETTING_WIRELESS_SEC, "Security", - "Security", + "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 " + NM_SETTING_WIRELESS_SECURITY_SETTING_NAME " setting.", NULL, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); }