NMSettingGsm: libnm-util Reference Manual

## NMSettingGsm NMSettingGsm — Describes GSM/3GPP-based mobile broadband properties |

## Functions

GQuark | nm_setting_gsm_error_quark ()
#define | NM_SETTING_GSM_BANDS_MAX
NMSetting * | nm_setting_gsm_new ()
const char * | nm_setting_gsm_get_number ()
const char * | nm_setting_gsm_get_username ()
const char * | nm_setting_gsm_get_password ()
const char * | nm_setting_gsm_get_apn ()
const char * | nm_setting_gsm_get_network_id ()
const char * | nm_setting_gsm_get_pin ()
gboolean | nm_setting_gsm_get_home_only ()
NMSettingSecretFlags | nm_setting_gsm_get_pin_flags ()
NMSettingSecretFlags | nm_setting_gsm_get_password_flags ()
int | nm_setting_gsm_get_network_type ()
guint32 | nm_setting_gsm_get_allowed_bands ()

## Properties

guint | allowed-bands | Read / Write / Construct
gchar * | apn | Read / Write
gboolean | home-only | Read / Write
gchar * | network-id | Read / Write
gint | network-type | Read / Write / Construct
gchar * | number | Read / Write
gchar * | password | Read / Write
guint | password-flags | Read / Write
gchar * | pin | Read / Write
guint | pin-flags | Read / Write
gchar * | username | Read / Write

## Types and Values

#define | NM_SETTING_GSM_SETTING_NAME
enum | NMSettingGsmError
#define | NM_SETTING_GSM_ERROR
#define | NM_SETTING_GSM_NUMBER
#define | NM_SETTING_GSM_USERNAME
#define | NM_SETTING_GSM_PASSWORD
#define | NM_SETTING_GSM_PASSWORD_FLAGS
#define | NM_SETTING_GSM_APN
#define | NM_SETTING_GSM_NETWORK_ID
#define | NM_SETTING_GSM_PIN
#define | NM_SETTING_GSM_PIN_FLAGS
#define | NM_SETTING_GSM_HOME_ONLY
#define | NM_SETTING_GSM_ALLOWED_BANDS
#define | NM_SETTING_GSM_NETWORK_TYPE
enum | NMSettingGsmNetworkType
enum | NMSettingGsmNetworkBand

## Object Hierarchy

        GEnum
        ├── NMSettingGsmError
        ├── NMSettingGsmNetworkBand
        ╰── NMSettingGsmNetworkType
        GObject
        ╰── NMSetting
            ╰── NMSettingGsm

## Includes

    #include <nm-setting-gsm.h>

## Description

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.

## Functions

### nm_setting_gsm_error_quark ()

    GQuark
    nm_setting_gsm_error_quark (void);

Registers an error quark for NMSettingGsm if necessary.

#### Returns

the error quark used for NMSettingGsm errors.

### NM_SETTING_GSM_BANDS_MAX

    #define             NM_SETTING_GSM_BANDS_MAX

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

No longer used.

NM_SETTING_GSM_BANDS_MAX macro indicate the maximal value that can be used as the allowed frequency bands (“allowed-bands” property).

### nm_setting_gsm_new ()

    NMSetting *
    nm_setting_gsm_new (void);

Creates a new NMSettingGsm object with default values.

#### Returns

the new empty NMSettingGsm object

### nm_setting_gsm_get_number ()

    const char *
    nm_setting_gsm_get_number (NMSettingGsm *setting);

#### Parameters

setting | the NMSettingGsm |

#### Returns

the “number” property of the setting

### nm_setting_gsm_get_username ()

    const char *
    nm_setting_gsm_get_username (NMSettingGsm *setting);

#### Parameters

setting | the NMSettingGsm |

#### Returns

the “username” property of the setting

### nm_setting_gsm_get_password ()

    const char *
    nm_setting_gsm_get_password (NMSettingGsm *setting);

#### Parameters

setting | the NMSettingGsm |

#### Returns

the “password” property of the setting

### nm_setting_gsm_get_apn ()

    const char *
    nm_setting_gsm_get_apn (NMSettingGsm *setting);

#### Parameters

setting | the NMSettingGsm |

#### Returns

the “apn” property of the setting

### nm_setting_gsm_get_network_id ()

    const char *
    nm_setting_gsm_get_network_id (NMSettingGsm *setting);

#### Parameters

setting | the NMSettingGsm |

#### Returns

the “network-id” property of the setting

### nm_setting_gsm_get_pin ()

    const char *
    nm_setting_gsm_get_pin (NMSettingGsm *setting);

#### Parameters

setting | the NMSettingGsm |

#### Returns

the “pin” property of the setting

### nm_setting_gsm_get_home_only ()

    gboolean
    nm_setting_gsm_get_home_only (NMSettingGsm *setting);

#### Parameters

setting | the NMSettingGsm |

#### Returns

the “home-only” property of the setting

### nm_setting_gsm_get_pin_flags ()

    NMSettingSecretFlags
    nm_setting_gsm_get_pin_flags (NMSettingGsm *setting);

#### Parameters

setting | the NMSettingGsm |

#### Returns

the NMSettingSecretFlags pertaining to the “pin”

### nm_setting_gsm_get_password_flags ()

    NMSettingSecretFlags
    nm_setting_gsm_get_password_flags (NMSettingGsm *setting);

#### Parameters

setting | the NMSettingGsm |

#### Returns

the NMSettingSecretFlags pertaining to the “password”

### nm_setting_gsm_get_network_type ()

    int
    nm_setting_gsm_get_network_type (NMSettingGsm *setting);

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

No longer used. Network type setting should be done talking to ModemManager directly.

#### Parameters

setting | the NMSettingGsm |

#### Returns

the “network-type” property of the setting

### nm_setting_gsm_get_allowed_bands ()

    guint32
    nm_setting_gsm_get_allowed_bands (NMSettingGsm *setting);

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

No longer used. Bands setting should be done talking to ModemManager directly.

#### Parameters

setting | the NMSettingGsm |

#### Returns

the “allowed-bands” property of the setting

## Types and Values

### NM_SETTING_GSM_SETTING_NAME

    #define NM_SETTING_GSM_SETTING_NAME "gsm"

### enum NMSettingGsmError

#### Members

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 |

### NM_SETTING_GSM_ERROR

    #define NM_SETTING_GSM_ERROR nm_setting_gsm_error_quark ()

### NM_SETTING_GSM_NUMBER

    #define NM_SETTING_GSM_NUMBER         "number"

### NM_SETTING_GSM_USERNAME

    #define NM_SETTING_GSM_USERNAME       "username"

### NM_SETTING_GSM_PASSWORD

    #define NM_SETTING_GSM_PASSWORD       "password"

### NM_SETTING_GSM_PASSWORD_FLAGS

    #define NM_SETTING_GSM_PASSWORD_FLAGS "password-flags"

### NM_SETTING_GSM_APN

    #define NM_SETTING_GSM_APN            "apn"

### NM_SETTING_GSM_NETWORK_ID

    #define NM_SETTING_GSM_NETWORK_ID     "network-id"

### NM_SETTING_GSM_PIN

    #define NM_SETTING_GSM_PIN            "pin"

### NM_SETTING_GSM_PIN_FLAGS

    #define NM_SETTING_GSM_PIN_FLAGS      "pin-flags"

### NM_SETTING_GSM_HOME_ONLY

    #define NM_SETTING_GSM_HOME_ONLY      "home-only"

### NM_SETTING_GSM_ALLOWED_BANDS

    #define NM_SETTING_GSM_ALLOWED_BANDS  "allowed-bands"

### NM_SETTING_GSM_NETWORK_TYPE

    #define NM_SETTING_GSM_NETWORK_TYPE   "network-type"

### enum NMSettingGsmNetworkType

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

No longer used.

NMSettingGsmNetworkType values indicate the allowed access technologies the device may use when connecting to this network.

#### Members

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 |
NM_SETTING_GSM_NETWORK_TYPE_PREFER_4G | 4G/LTE-type technologies are preferred but 3G/2/-type technologies may be used as a fallback |
NM_SETTING_GSM_NETWORK_TYPE_4G | only 4G/LTE type technologies may be used |

### enum NMSettingGsmNetworkBand

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

No longer used.

NMSettingGsmNetworkBand values indicate the allowed frequency bands the device may use when connecting to this network.

#### Members

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

## Property Details

### The `“allowed-bands”` property

      “allowed-bands”            guint

Bitfield of allowed frequency bands. Note that not all devices allow frequency band control. Permitted values are those specified by NMSettingGsmNetworkBand.

`NMSettingGsm:allowed-bands` has been deprecated since version 0.9.10 and should not be used in newly-written code.

No longer used. Band setting should be done by talking to ModemManager directly.

Flags: Read / Write / Construct

Allowed values: <= 16383

Default value: 1

### The `“apn”` property

      “apn”                      gchar *

The GPRS Access Point Name specifying the APN used when establishing a data session with the GSM-based network. The APN often determines how the user will be billed for their network usage and whether the user has access to the Internet or just a provider-specific walled-garden, so it is important to use the correct APN for the user's mobile broadband plan. The APN may only be composed of the characters a-z, 0-9, ., and - per GSM 03.60 Section 14.9.

Flags: Read / Write

Default value: NULL

### The `“home-only”` property

      “home-only”                gboolean

When `TRUE`, only connections to the home network will be allowed. Connections to roaming networks will not be made.

Flags: Read / Write

Default value: FALSE

### The `“network-id”` property

      “network-id”               gchar *

The Network ID (GSM LAI format, ie MCC-MNC) to force specific network registration. If the Network ID is specified, NetworkManager will attempt to force the device to register only on the specified network. This can be used to ensure that the device does not roam when direct roaming control of the device is not otherwise possible.

Flags: Read / Write

Default value: NULL

### The `“network-type”` property

      “network-type”             gint

Network preference to force the device to only use specific network technologies. The permitted values are `NM_SETTING_GSM_NETWORK_TYPE_ANY`, `NM_SETTING_GSM_NETWORK_TYPE_UMTS_HSPA`, `NM_SETTING_GSM_NETWORK_TYPE_GPRS_EDGE`, `NM_SETTING_GSM_NETWORK_TYPE_PREFER_UMTS_HSPA`, `NM_SETTING_GSM_NETWORK_TYPE_PREFER_GPRS_EDGE`, `NM_SETTING_GSM_NETWORK_TYPE_PREFER_4G`, and `NM_SETTING_GSM_NETWORK_TYPE_4G`. Note that not all devices allow network preference control.

`NMSettingGsm:network-type` has been deprecated since version 0.9.10 and should not be used in newly-written code.

No longer used. Network type setting should be done by talking to ModemManager directly.

Flags: Read / Write / Construct

Allowed values: [-1,5]

Default value: -1

### The `“number”` property

      “number”                   gchar *

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.

Flags: Read / Write

Default value: NULL

### The `“password”` property

      “password”                 gchar *

The password used to authenticate with the network, if required. Many providers do not require a password, or accept any password. But if a password is required, it is specified here.

Flags: Read / Write

Default value: NULL

### The `“password-flags”` property

      “password-flags”           guint

Flags indicating how to handle the “password” property.

Flags: Read / Write

Allowed values: <= 7

Default value: 0

### The `“pin”` property

      “pin”                      gchar *

If the SIM is locked with a PIN it must be unlocked before any other operations are requested. Specify the PIN here to allow operation of the device.

Flags: Read / Write

Default value: NULL

### The `“pin-flags”` property

      “pin-flags”                guint

Flags indicating how to handle the “pin” property.

Flags: Read / Write

Allowed values: <= 7

Default value: 0

### The `“username”` property

      “username”                 gchar *

The username used to authenticate with the network, if required. Many providers do not require a username, or accept any username. But if a username is required, it is specified here.

Flags: Read / Write

Default value: NULL