From 2da074db78ae363262584f09150c3d7400a37f2c Mon Sep 17 00:00:00 2001 From: Dan Williams Date: Tue, 5 Jul 2011 14:19:54 -0500 Subject: [PATCH] docs: update GSM setting documentation --- libnm-util/nm-setting-gsm.c | 106 +++++++++++++++++++++++++++++++----- libnm-util/nm-setting-gsm.h | 48 +++++++++++++++- 2 files changed, 139 insertions(+), 15 deletions(-) diff --git a/libnm-util/nm-setting-gsm.c b/libnm-util/nm-setting-gsm.c index 643702c79..7033541bd 100644 --- a/libnm-util/nm-setting-gsm.c +++ b/libnm-util/nm-setting-gsm.c @@ -29,6 +29,23 @@ #include "nm-utils.h" #include "nm-setting-private.h" +/** + * SECTION:nm-setting-gsm + * @short_description: Describes GSM/3GPP-based mobile broadband properties + * @include: nm-setting-gsm.h + * + * The #NMSettingGsm object is a #NMSetting subclass that describes + * properties that allow connections to 3GPP-based mobile broadband + * networks, including those using GPRS/EDGE and UMTS/HSPA technology. + */ + +/** + * nm_setting_gsm_error_quark: + * + * Registers an error quark for #NMSettingGsm if necessary. + * + * Returns: the error quark used for #NMSettingGsm errors. + **/ GQuark nm_setting_gsm_error_quark (void) { @@ -103,12 +120,25 @@ enum { LAST_PROP }; +/** + * nm_setting_gsm_new: + * + * Creates a new #NMSettingGsm object with default values. + * + * Returns: the new empty #NMSettingGsm object + **/ NMSetting * nm_setting_gsm_new (void) { return (NMSetting *) g_object_new (NM_TYPE_SETTING_GSM, NULL); } +/** + * nm_setting_gsm_get_number: + * @setting: the #NMSettingGsm + * + * Returns: the #NMSettingGsm:number property of the setting + **/ const char * nm_setting_gsm_get_number (NMSettingGsm *setting) { @@ -117,6 +147,12 @@ nm_setting_gsm_get_number (NMSettingGsm *setting) return NM_SETTING_GSM_GET_PRIVATE (setting)->number; } +/** + * nm_setting_gsm_get_username: + * @setting: the #NMSettingGsm + * + * Returns: the #NMSettingGsm:username property of the setting + **/ const char * nm_setting_gsm_get_username (NMSettingGsm *setting) { @@ -125,6 +161,12 @@ nm_setting_gsm_get_username (NMSettingGsm *setting) return NM_SETTING_GSM_GET_PRIVATE (setting)->username; } +/** + * nm_setting_gsm_get_password: + * @setting: the #NMSettingGsm + * + * Returns: the #NMSettingGsm:password property of the setting + **/ const char * nm_setting_gsm_get_password (NMSettingGsm *setting) { @@ -147,6 +189,12 @@ nm_setting_gsm_get_password_flags (NMSettingGsm *setting) return NM_SETTING_GSM_GET_PRIVATE (setting)->password_flags; } +/** + * nm_setting_gsm_get_apn: + * @setting: the #NMSettingGsm + * + * Returns: the #NMSettingGsm:apn property of the setting + **/ const char * nm_setting_gsm_get_apn (NMSettingGsm *setting) { @@ -155,6 +203,12 @@ nm_setting_gsm_get_apn (NMSettingGsm *setting) return NM_SETTING_GSM_GET_PRIVATE (setting)->apn; } +/** + * nm_setting_gsm_get_network_id: + * @setting: the #NMSettingGsm + * + * Returns: the #NMSettingGsm:network-id property of the setting + **/ const char * nm_setting_gsm_get_network_id (NMSettingGsm *setting) { @@ -163,6 +217,12 @@ nm_setting_gsm_get_network_id (NMSettingGsm *setting) return NM_SETTING_GSM_GET_PRIVATE (setting)->network_id; } +/** + * nm_setting_gsm_get_network_type: + * @setting: the #NMSettingGsm + * + * Returns: the #NMSettingGsm:network-type property of the setting + **/ int nm_setting_gsm_get_network_type (NMSettingGsm *setting) { @@ -171,6 +231,12 @@ nm_setting_gsm_get_network_type (NMSettingGsm *setting) return NM_SETTING_GSM_GET_PRIVATE (setting)->network_type; } +/** + * nm_setting_gsm_get_allowed_bands: + * @setting: the #NMSettingGsm + * + * Returns: the #NMSettingGsm:allowed-bands property of the setting + **/ guint32 nm_setting_gsm_get_allowed_bands (NMSettingGsm *setting) { @@ -179,6 +245,12 @@ nm_setting_gsm_get_allowed_bands (NMSettingGsm *setting) return NM_SETTING_GSM_GET_PRIVATE (setting)->allowed_bands; } +/** + * nm_setting_gsm_get_pin: + * @setting: the #NMSettingGsm + * + * Returns: the #NMSettingGsm:pin property of the setting + **/ const char * nm_setting_gsm_get_pin (NMSettingGsm *setting) { @@ -201,6 +273,12 @@ nm_setting_gsm_get_pin_flags (NMSettingGsm *setting) return NM_SETTING_GSM_GET_PRIVATE (setting)->pin_flags; } +/** + * nm_setting_gsm_get_home_only: + * @setting: the #NMSettingGsm + * + * Returns: the #NMSettingGsm:home-only property of the setting + **/ gboolean nm_setting_gsm_get_home_only (NMSettingGsm *setting) { @@ -481,19 +559,20 @@ nm_setting_gsm_class_init (NMSettingGsmClass *setting_class) * NMSettingGsm:number: * * Number to dial when establishing a PPP data session with the GSM-based - * mobile broadband network. In most cases, leave the number blank and a - * number selecting the APN specified in the 'apn' property will be used - * automatically when required. + * mobile broadband network. Many modems do not require PPP for connections + * to the mobile network and thus this property should be left blank, which + * allows NetworkManager to select the appropriate settings automatically. **/ g_object_class_install_property (object_class, PROP_NUMBER, g_param_spec_string (NM_SETTING_GSM_NUMBER, "Number", - "Number to dial when establishing a PPP data session " - "with the GSM-based mobile broadband network. In most " - "cases, leave the number blank and a number selecting " - "the APN specified in the 'apn' property will be used " - "automatically when required.", + "Number to dial when establishing a PPP data session " + "with the GSM-based mobile broadband network. Many " + "modems do not require PPP for connections to the " + "mobile network and thus this property should be left " + "blank, which allows NetworkManager to select the " + "appropriate settings automatically.", NULL, G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE)); @@ -599,9 +678,9 @@ nm_setting_gsm_class_init (NMSettingGsmClass *setting_class) * NMSettingGsm:network-type: * * Network preference to force the device to only use specific network - * technologies. The permitted values are: -1: any, 0: 3G only, - * 1: GPRS/EDGE only, 2: prefer 3G, and 3: prefer 2G. Note that not all - * devices allow network preference control. + * technologies. Permitted values are those specified by + * #NMSettingGsmNetworkType. Note that not all devices allow network + * preference control. **/ g_object_class_install_property (object_class, PROP_NETWORK_TYPE, @@ -621,7 +700,8 @@ nm_setting_gsm_class_init (NMSettingGsmClass *setting_class) * NMSettingGsm:allowed-bands: * * Bitfield of allowed frequency bands. Note that not all devices allow - * frequency band control. + * frequency band control. Permitted values are those specified by + * #NMSettingGsmNetworkBand. **/ g_object_class_install_property (object_class, PROP_ALLOWED_BANDS, @@ -668,7 +748,7 @@ nm_setting_gsm_class_init (NMSettingGsmClass *setting_class) /** * NMSettingGsm:pin-flags: * - * Flags indicating how to handle #NMSettingGsm:pin:. + * Flags indicating how to handle #NMSettingGsm:pin. **/ g_object_class_install_property (object_class, PROP_PIN_FLAGS, g_param_spec_uint (NM_SETTING_GSM_PIN_FLAGS, diff --git a/libnm-util/nm-setting-gsm.h b/libnm-util/nm-setting-gsm.h index 92aa5f797..6459a4abf 100644 --- a/libnm-util/nm-setting-gsm.h +++ b/libnm-util/nm-setting-gsm.h @@ -39,8 +39,16 @@ G_BEGIN_DECLS #define NM_SETTING_GSM_SETTING_NAME "gsm" -typedef enum -{ +/** + * NMSettingGsmError: + * @NM_SETTING_GSM_ERROR_UNKNOWN: unknown or unclassified error + * @NM_SETTING_GSM_ERROR_INVALID_PROPERTY: the property was invalid + * @NM_SETTING_GSM_ERROR_MISSING_PROPERTY: the property was missing and is + * required + * @NM_SETTING_GSM_ERROR_MISSING_SERIAL_SETTING: the required #NMSettingSerial + * is missing in the connection + */ +typedef enum { NM_SETTING_GSM_ERROR_UNKNOWN = 0, NM_SETTING_GSM_ERROR_INVALID_PROPERTY, NM_SETTING_GSM_ERROR_MISSING_PROPERTY, @@ -65,6 +73,21 @@ GQuark nm_setting_gsm_error_quark (void); #define NM_SETTING_GSM_PIN_FLAGS "pin-flags" #define NM_SETTING_GSM_HOME_ONLY "home-only" +/** + * NMSettingGsmNetworkType: + * @NM_SETTING_GSM_NETWORK_TYPE_ANY: any access technology may be used + * @NM_SETTING_GSM_NETWORK_TYPE_UMTS_HSPA: only 3G-type (UMTS and HSPA) + * technologies may be used + * @NM_SETTING_GSM_NETWORK_TYPE_GPRS_EDGE: only 2G-type (GPRS and EDGE) + * technologies may be used + * @NM_SETTING_GSM_NETWORK_TYPE_PREFER_UMTS_HSPA: 3G-type technologies are + * preferred but 2G-type technologies may be used as a fallback + * @NM_SETTING_GSM_NETWORK_TYPE_PREFER_GPRS_EDGE: 2G-type technologies are + * preferred but 3G-type technologies may be used as a fallback + * + * #NMSettingGsmNetworkType values indicate the allowed access technologies + * the device may use when connecting to this network. + */ typedef enum { NM_SETTING_GSM_NETWORK_TYPE_ANY = -1, NM_SETTING_GSM_NETWORK_TYPE_UMTS_HSPA = 0, @@ -73,6 +96,27 @@ typedef enum { NM_SETTING_GSM_NETWORK_TYPE_PREFER_GPRS_EDGE = 3 } NMSettingGsmNetworkType; +/** + * NMSettingGsmNetworkBand: + * @NM_SETTING_GSM_BAND_UNKNOWN: unknown or no band specified + * @NM_SETTING_GSM_BAND_ANY: any band is allowed + * @NM_SETTING_GSM_BAND_EGSM: 900 MHz original GSM band + * @NM_SETTING_GSM_BAND_DCS: 1800 MHz DCS band + * @NM_SETTING_GSM_BAND_PCS: US 1900 MHz PCS band + * @NM_SETTING_GSM_BAND_G850: US 850 MHz Cellular band + * @NM_SETTING_GSM_BAND_U2100: WCDMA 3GPP UMTS 2100 MHz (Class I) + * @NM_SETTING_GSM_BAND_U1800: WCDMA 3GPP UMTS 1800 MHz (Class III) + * @NM_SETTING_GSM_BAND_U17IV: WCDMA 3GPP AWS 1700/2100 MHz (Class IV) + * @NM_SETTING_GSM_BAND_U800: WCDMA 3GPP UMTS 800 MHz (Class VI) + * @NM_SETTING_GSM_BAND_U850: WCDMA 3GPP UMTS 850 MHz (Class V) + * @NM_SETTING_GSM_BAND_U900: WCDMA 3GPP UMTS 900 MHz (Class VIII) + * @NM_SETTING_GSM_BAND_U17IX: WCDMA 3GPP UMTS 1700 MHz (Class IX) + * @NM_SETTING_GSM_BAND_U1900: WCDMA 3GPP UMTS 1900 MHz (Class II) + * @NM_SETTING_GSM_BAND_U2600: WCDMA 3GPP UMTS 2600 MHz (Class VII, internal) + * + * #NMSettingGsmNetworkBand values indicate the allowed frequency bands + * the device may use when connecting to this network. + */ typedef enum { NM_SETTING_GSM_BAND_UNKNOWN = 0x00000000, NM_SETTING_GSM_BAND_ANY = 0x00000001,