NMSettingConnection

## NMSettingConnection NMSettingConnection — Describes general connection properties |

## Synopsis

    #include <nm-setting-connection.h>

    #define             NM_SETTING_CONNECTION_SETTING_NAME
    enum                NMSettingConnectionError;
    #define             NM_SETTING_CONNECTION_ERROR
    GQuark              nm_setting_connection_error_quark   (void);
    #define             NM_SETTING_CONNECTION_ID
    #define             NM_SETTING_CONNECTION_UUID
    #define             NM_SETTING_CONNECTION_INTERFACE_NAME
    #define             NM_SETTING_CONNECTION_TYPE
    #define             NM_SETTING_CONNECTION_AUTOCONNECT
    #define             NM_SETTING_CONNECTION_TIMESTAMP
    #define             NM_SETTING_CONNECTION_READ_ONLY
    #define             NM_SETTING_CONNECTION_PERMISSIONS
    #define             NM_SETTING_CONNECTION_ZONE
    #define             NM_SETTING_CONNECTION_MASTER
    #define             NM_SETTING_CONNECTION_SLAVE_TYPE
    #define             NM_SETTING_CONNECTION_SECONDARIES
    #define             NM_SETTING_CONNECTION_GATEWAY_PING_TIMEOUT
                        NMSettingConnection;
                        NMSettingConnectionClass;
    NMSetting *         nm_setting_connection_new           (void);
    const char *        nm_setting_connection_get_id        (NMSettingConnection *setting);
    const char *        nm_setting_connection_get_uuid      (NMSettingConnection *setting);
    const char *        nm_setting_connection_get_interface_name
                                                            (NMSettingConnection *setting);
    const char *        nm_setting_connection_get_connection_type
                                                            (NMSettingConnection *setting);
    gboolean            nm_setting_connection_get_autoconnect
                                                            (NMSettingConnection *setting);
    guint64             nm_setting_connection_get_timestamp (NMSettingConnection *setting);
    gboolean            nm_setting_connection_get_read_only (NMSettingConnection *setting);
    guint32             nm_setting_connection_get_num_permissions
                                                            (NMSettingConnection *setting);
    gboolean            nm_setting_connection_get_permission
                                                            (NMSettingConnection *setting,
                                                             guint32 idx,
                                                             const char **out_ptype,
                                                             const char **out_pitem,
                                                             const char **out_detail);
    const char *        nm_setting_connection_get_zone      (NMSettingConnection *setting);
    gboolean            nm_setting_connection_permissions_user_allowed
                                                            (NMSettingConnection *setting,
                                                             const char *uname);
    gboolean            nm_setting_connection_add_permission
                                                            (NMSettingConnection *setting,
                                                             const char *ptype,
                                                             const char *pitem,
                                                             const char *detail);
    void                nm_setting_connection_remove_permission
                                                            (NMSettingConnection *setting,
                                                             guint32 idx);
    gboolean            nm_setting_connection_remove_permission_by_value
                                                            (NMSettingConnection *setting,
                                                             const char *ptype,
                                                             const char *pitem,
                                                             const char *detail);
    const char *        nm_setting_connection_get_master    (NMSettingConnection *setting);
    gboolean            nm_setting_connection_is_slave_type (NMSettingConnection *setting,
                                                             const char *type);
    const char *        nm_setting_connection_get_slave_type
                                                            (NMSettingConnection *setting);
    guint32             nm_setting_connection_get_num_secondaries
                                                            (NMSettingConnection *setting);
    const char *        nm_setting_connection_get_secondary (NMSettingConnection *setting,
                                                             guint32 idx);
    gboolean            nm_setting_connection_add_secondary (NMSettingConnection *setting,
                                                             const char *sec_uuid);
    void                nm_setting_connection_remove_secondary
                                                            (NMSettingConnection *setting,
                                                             guint32 idx);
    gboolean            nm_setting_connection_remove_secondary_by_value
                                                            (NMSettingConnection *setting,
                                                             const char *sec_uuid);
    guint32             nm_setting_connection_get_gateway_ping_timeout
                                                            (NMSettingConnection *setting);

## Object Hierarchy

      GEnum
       +----NMSettingConnectionError

      GObject
       +----NMSetting
             +----NMSettingConnection

## Properties

      "autoconnect"              gboolean              : Read / Write / Construct
      "gateway-ping-timeout"     guint                 : Read / Write / Construct
      "id"                       gchar*                : Read / Write
      "interface-name"           gchar*                : Read / Write
      "master"                   gchar*                : Read / Write
      "permissions"              GSList_gchararray_*   : Read / Write
      "read-only"                gboolean              : Read / Write / Construct
      "secondaries"              GSList_gchararray_*   : Read / Write
      "slave-type"               gchar*                : Read / Write
      "timestamp"                guint64               : Read / Write / Construct
      "type"                     gchar*                : Read / Write
      "uuid"                     gchar*                : Read / Write
      "zone"                     gchar*                : Read / Write / Construct

## Description

The NMSettingConnection object is a NMSetting subclass that describes properties that apply to all NMConnection objects, regardless of what type of network connection they describe. Each NMConnection object must contain a NMSettingConnection setting.

## Details

### NM_SETTING_CONNECTION_SETTING_NAME

    #define NM_SETTING_CONNECTION_SETTING_NAME "connection"

### enum NMSettingConnectionError

    typedef enum {
    	NM_SETTING_CONNECTION_ERROR_UNKNOWN = 0,            /*< nick=UnknownError >*/
    	NM_SETTING_CONNECTION_ERROR_INVALID_PROPERTY,       /*< nick=InvalidProperty >*/
    	NM_SETTING_CONNECTION_ERROR_MISSING_PROPERTY,       /*< nick=MissingProperty >*/
    	NM_SETTING_CONNECTION_ERROR_TYPE_SETTING_NOT_FOUND, /*< nick=TypeSettingNotFound >*/
    	NM_SETTING_CONNECTION_ERROR_IP_CONFIG_NOT_ALLOWED,  /*< nick=IpConfigNotAllowed >*/
    } NMSettingConnectionError;

Describes errors that may result from operations involving a NMSettingConnection.

`NM_SETTING_CONNECTION_ERROR_UNKNOWN` | unknown or unclassified error
`NM_SETTING_CONNECTION_ERROR_INVALID_PROPERTY` | the property's value is invalid
`NM_SETTING_CONNECTION_ERROR_MISSING_PROPERTY` | a required property is not present
`NM_SETTING_CONNECTION_ERROR_TYPE_SETTING_NOT_FOUND` | the NMSetting object referenced by the setting name contained in the "type" property was not present in the NMConnection
`NM_SETTING_CONNECTION_ERROR_IP_CONFIG_NOT_ALLOWED` | ip configuration is not allowed to be present.

### NM_SETTING_CONNECTION_ERROR

    #define NM_SETTING_CONNECTION_ERROR nm_setting_connection_error_quark ()

### nm_setting_connection_error_quark ()

    GQuark              nm_setting_connection_error_quark   (void);

Registers an error quark for NMSettingConnection if necessary.

Returns : | the error quark used for NMSettingConnection errors.

### NM_SETTING_CONNECTION_ID

    #define NM_SETTING_CONNECTION_ID             "id"

### NM_SETTING_CONNECTION_UUID

    #define NM_SETTING_CONNECTION_UUID           "uuid"

### NM_SETTING_CONNECTION_INTERFACE_NAME

    #define NM_SETTING_CONNECTION_INTERFACE_NAME "interface-name"

### NM_SETTING_CONNECTION_TYPE

    #define NM_SETTING_CONNECTION_TYPE           "type"

### NM_SETTING_CONNECTION_AUTOCONNECT

    #define NM_SETTING_CONNECTION_AUTOCONNECT    "autoconnect"

### NM_SETTING_CONNECTION_TIMESTAMP

    #define NM_SETTING_CONNECTION_TIMESTAMP      "timestamp"

### NM_SETTING_CONNECTION_READ_ONLY

    #define NM_SETTING_CONNECTION_READ_ONLY      "read-only"

### NM_SETTING_CONNECTION_PERMISSIONS

    #define NM_SETTING_CONNECTION_PERMISSIONS    "permissions"

### NM_SETTING_CONNECTION_ZONE

    #define NM_SETTING_CONNECTION_ZONE           "zone"

### NM_SETTING_CONNECTION_MASTER

    #define NM_SETTING_CONNECTION_MASTER         "master"

### NM_SETTING_CONNECTION_SLAVE_TYPE

    #define NM_SETTING_CONNECTION_SLAVE_TYPE     "slave-type"

### NM_SETTING_CONNECTION_SECONDARIES

    #define NM_SETTING_CONNECTION_SECONDARIES    "secondaries"

### NM_SETTING_CONNECTION_GATEWAY_PING_TIMEOUT

    #define NM_SETTING_CONNECTION_GATEWAY_PING_TIMEOUT "gateway-ping-timeout"

### NMSettingConnection

    typedef struct _NMSettingConnection NMSettingConnection;

The NMSettingConnection struct contains only private data. It should only be accessed through the functions described below.

### NMSettingConnectionClass

    typedef struct {
    	NMSettingClass parent;

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

### nm_setting_connection_new ()

    NMSetting *         nm_setting_connection_new           (void);

Creates a new NMSettingConnection object with default values.

Returns : | the new empty NMSettingConnection object

### nm_setting_connection_get_id ()

    const char *        nm_setting_connection_get_id        (NMSettingConnection *setting);

Returns the "id" property of the connection.

`setting` : | the NMSettingConnection
Returns : | the connection ID

### nm_setting_connection_get_uuid ()

    const char *        nm_setting_connection_get_uuid      (NMSettingConnection *setting);

Returns the "uuid" property of the connection.

`setting` : | the NMSettingConnection
Returns : | the connection UUID

### nm_setting_connection_get_interface_name ()

    const char *        nm_setting_connection_get_interface_name
                                                            (NMSettingConnection *setting);

Returns the "interface-name" property of the connection.

`setting` : | the NMSettingConnection
Returns : | the connection's interface name

Since 0.9.10

### nm_setting_connection_get_connection_type ()

    const char *        nm_setting_connection_get_connection_type
                                                            (NMSettingConnection *setting);

Returns the "type" property of the connection.

`setting` : | the NMSettingConnection
Returns : | the connection type

### nm_setting_connection_get_autoconnect ()

    gboolean            nm_setting_connection_get_autoconnect
                                                            (NMSettingConnection *setting);

Returns the "autoconnect" property of the connection.

`setting` : | the NMSettingConnection
Returns : | the connection's autoconnect behavior

### nm_setting_connection_get_timestamp ()

    guint64             nm_setting_connection_get_timestamp (NMSettingConnection *setting);

Returns the "timestamp" property of the connection.

`setting` : | the NMSettingConnection
Returns : | the connection's timestamp

### nm_setting_connection_get_read_only ()

    gboolean            nm_setting_connection_get_read_only (NMSettingConnection *setting);

Returns the "read-only" property of the connection.

`setting` : | the NMSettingConnection
Returns : | `TRUE` if the connection is read-only, `FALSE` if it is not

### nm_setting_connection_get_num_permissions ()

    guint32             nm_setting_connection_get_num_permissions
                                                            (NMSettingConnection *setting);

Returns the number of entires in the "permissions" property of this setting.

`setting` : | the NMSettingConnection
Returns : | the number of permissions entires

### nm_setting_connection_get_permission ()

    gboolean            nm_setting_connection_get_permission
                                                            (NMSettingConnection *setting,
                                                             guint32 idx,
                                                             const char **out_ptype,
                                                             const char **out_pitem,
                                                             const char **out_detail);

Retrieve one of the entries of the "permissions" property of this setting.

`setting` : | the NMSettingConnection
`idx` : | the zero-based index of the permissions entry
`out_ptype` : | on return, the permission type (at this time, always "user")
`out_pitem` : | on return, the permission item (formatted accoring to `ptype`, see "permissions" for more detail
`out_detail` : | on return, the permission detail (at this time, always `NULL`)
Returns : | `TRUE` if a permission was returned, `FALSE` if `idx` was invalid

### nm_setting_connection_get_zone ()

    const char *        nm_setting_connection_get_zone      (NMSettingConnection *setting);

Returns the "zone" property of the connection.

`setting` : | the NMSettingConnection
Returns : | the trust level of a connection

### nm_setting_connection_permissions_user_allowed ()

    gboolean            nm_setting_connection_permissions_user_allowed
                                                            (NMSettingConnection *setting,
                                                             const char *uname);

Checks whether the given username is allowed to view/access this connection.

`setting` : | the NMSettingConnection
`uname` : | the user name to check permissions for
Returns : | `TRUE` if the requested user is allowed to view this connection, `FALSE` if the given user is not allowed to view this connection

### nm_setting_connection_add_permission ()

    gboolean            nm_setting_connection_add_permission
                                                            (NMSettingConnection *setting,
                                                             const char *ptype,
                                                             const char *pitem,
                                                             const char *detail);

Adds a permission to the connection's permission list. At this time, only the "user" permission type is supported, and `pitem` must be a username. See "permissions": for more details.

`setting` : | the NMSettingConnection
`ptype` : | the permission type; at this time only "user" is supported
`pitem` : | the permission item formatted as required for `ptype`
`detail` : | unused at this time; must be `NULL`. [allow-none]
Returns : | `TRUE` if the permission was unique and was successfully added to the list, `FALSE` if `ptype` or `pitem` was invalid or it the permission was already present in the list

### nm_setting_connection_remove_permission ()

    void                nm_setting_connection_remove_permission
                                                            (NMSettingConnection *setting,
                                                             guint32 idx);

Removes the permission at index `idx` from the connection.

`setting` : | the NMSettingConnection
`idx` : | the zero-based index of the permission to remove

### nm_setting_connection_remove_permission_by_value ()

    gboolean            nm_setting_connection_remove_permission_by_value
                                                            (NMSettingConnection *setting,
                                                             const char *ptype,
                                                             const char *pitem,
                                                             const char *detail);

Removes the permission from the connection. At this time, only the "user" permission type is supported, and `pitem` must be a username. See "permissions": for more details.

`setting` : | the NMSettingConnection
`ptype` : | the permission type; at this time only "user" is supported
`pitem` : | the permission item formatted as required for `ptype`
`detail` : | unused at this time; must be `NULL`. [allow-none]
Returns : | `TRUE` if the permission was found and removed; `FALSE` if it was not.

Since 0.9.10

### nm_setting_connection_get_master ()

    const char *        nm_setting_connection_get_master    (NMSettingConnection *setting);

Returns the "master" property of the connection.

`setting` : | the NMSettingConnection
Returns : | interface name of the master device or UUID of the master connection.

### nm_setting_connection_is_slave_type ()

    gboolean            nm_setting_connection_is_slave_type (NMSettingConnection *setting,
                                                             const char *type);

`setting` : | the NMSettingConnection
`type` : | the setting name (ie NM_SETTING_BOND_SETTING_NAME) to be matched against `setting`'s slave type
Returns : | `TRUE` if connection is of the given slave `type`

### nm_setting_connection_get_slave_type ()

    const char *        nm_setting_connection_get_slave_type
                                                            (NMSettingConnection *setting);

Returns the "slave-type" property of the connection.

`setting` : | the NMSettingConnection
Returns : | the type of slave this connection is, if any

### nm_setting_connection_get_num_secondaries ()

    guint32             nm_setting_connection_get_num_secondaries
                                                            (NMSettingConnection *setting);

`setting` : | the NMSettingConnection
Returns : | the number of configured secondary connection UUIDs

Since 0.9.8

### nm_setting_connection_get_secondary ()

    const char *        nm_setting_connection_get_secondary (NMSettingConnection *setting,
                                                             guint32 idx);

`setting` : | the NMSettingConnection
`idx` : | the zero-based index of the secondary connection UUID entry
Returns : | the secondary connection UUID at index `idx`

Since 0.9.8

### nm_setting_connection_add_secondary ()

    gboolean            nm_setting_connection_add_secondary (NMSettingConnection *setting,
                                                             const char *sec_uuid);

Adds a new secondary connetion UUID to the setting.

`setting` : | the NMSettingConnection
`sec_uuid` : | the secondary connection UUID to add
Returns : | `TRUE` if the secondary connection UUID was added; `FALSE` if the UUID was already present

Since 0.9.8

### nm_setting_connection_remove_secondary ()

    void                nm_setting_connection_remove_secondary
                                                            (NMSettingConnection *setting,
                                                             guint32 idx);

Removes the secondary coonnection UUID at index `idx`.

`setting` : | the NMSettingConnection
`idx` : | index number of the secondary connection UUID

Since 0.9.8

### nm_setting_connection_remove_secondary_by_value ()

    gboolean            nm_setting_connection_remove_secondary_by_value
                                                            (NMSettingConnection *setting,
                                                             const char *sec_uuid);

Removes the secondary coonnection UUID `sec_uuid`.

`setting` : | the NMSettingConnection
`sec_uuid` : | the secondary connection UUID to remove
Returns : | `TRUE` if the secondary connection UUID was found and removed; `FALSE` if it was not.

Since 0.9.10

### nm_setting_connection_get_gateway_ping_timeout ()

    guint32             nm_setting_connection_get_gateway_ping_timeout
                                                            (NMSettingConnection *setting);

`setting` : | the NMSettingConnection
Returns : | the value contained in the "gateway-ping-timeout" property.

Since 0.9.10

## Property Details

### The `"autoconnect"` property

      "autoconnect"              gboolean              : Read / Write / Construct

Whether or not the connection should be automatically connected by NetworkManager when the resources for the connection are available. `TRUE` to automatically activate the connection, `FALSE` to require manual intervention to activate the connection.

Default value: TRUE

### The `"gateway-ping-timeout"` property

      "gateway-ping-timeout"     guint                 : Read / Write / Construct

If greater than zero, delay success of IP addressing until either the timeout is reached, or an IP gateway replies to a ping.

Allowed values: <= 30

Default value: 0

Since 0.9.10

### The `"id"` property

      "id"                       gchar*                : Read / Write

A human readable unique identifier for the connection, like "Work Wi-Fi" or "T-Mobile 3G".

Default value: NULL

### The `"interface-name"` property

      "interface-name"           gchar*                : Read / Write

The name of the network interface this connection is bound to. If not set, then the connection can be attached to any interface of the appropriate type (subject to restrictions imposed by other settings).

For connection types where interface names cannot easily be made persistent (e.g. mobile broadband or USB Ethernet), this property should not be used. Setting this property restricts the interfaces a connection can be used with, and if interface names change or are reordered the connection may be applied to the wrong interface.

Default value: NULL

Since 0.9.10

### The `"master"` property

      "master"                   gchar*                : Read / Write

Interface name of the master device or UUID of the master connection.

Default value: NULL

### The `"permissions"` property

      "permissions"              GSList_gchararray_*   : Read / Write

An array of strings defining what access a given user has to this connection. If this is `NULL` or empty, all users are allowed to access this connection. Otherwise a user is allowed to access this connection if and only if they are in this list. Each entry is of the form "[type]:[id]:[reserved]"; for example, "user:dcbw:blah".

At this time only the "user" [type] is allowed. Any other values are ignored and reserved for future use. [id] is the username that this permission refers to, which may not contain the ":" character. Any [reserved] information present must be ignored and is reserved for future use. All of [type], [id], and [reserved] must be valid UTF-8.

### The `"read-only"` property

      "read-only"                gboolean              : Read / Write / Construct

`FALSE` if the connection can be modified using the provided settings service's D-Bus interface with the right privileges, or `TRUE` if the connection is read-only and cannot be modified.

Default value: FALSE

### The `"secondaries"` property

      "secondaries"              GSList_gchararray_*   : Read / Write

List of connection UUIDs that should be activated when the base connection itself is activated. Currently only VPN connections are supported.

Since 0.9.8

### The `"slave-type"` property

      "slave-type"               gchar*                : Read / Write

Setting name of the device type of this slave's master connection (eg, `NM_SETTING_BOND_SETTING_NAME`), or `NULL` if this connection is not a slave.

Default value: NULL

### The `"timestamp"` property

      "timestamp"                guint64               : Read / Write / Construct

The time, in seconds since the Unix Epoch, that the connection was last _successfully_ fully activated.

NetworkManager updates the connection timestamp periodically when the connection is active to ensure that an active connection has the latest timestamp. The property is only meant for reading (changes to this property will not be preserved).

Default value: 0

### The `"type"` property

      "type"                     gchar*                : Read / Write

Base type of the connection. For hardware-dependent connections, should contain the setting name of the hardware-type specific setting (ie, "802-3-ethernet" or "802-11-wireless" or "bluetooth", etc), and for non-hardware dependent connections like VPN or otherwise, should contain the setting name of that setting type (ie, "vpn" or "bridge", etc).

Default value: NULL

### The `"uuid"` property

      "uuid"                     gchar*                : Read / Write

A universally unique identifier for the connection, for example generated with libuuid. It should be assigned when the connection is created, and never changed as long as the connection still applies to the same network. For example, it should not be changed when the "id" property or NMSettingIP4Config changes, but might need to be re-created when the Wi-Fi SSID, mobile broadband network provider, or "type" property changes.

The UUID must be in the format "2815492f-7e56-435e-b2e9-246bd7cdc664" (ie, contains only hexadecimal characters and "-"). A suitable UUID may be generated by `nm_utils_uuid_generate()` or `nm_utils_uuid_generate_from_string()`.

Default value: NULL

### The `"zone"` property

      "zone"                     gchar*                : Read / Write / Construct

The trust level of a the connection. Free form case-insensitive string (for example "Home", "Work", "Public"). `NULL` or unspecified zone means the connection will be placed in the default zone as defined by the firewall.

Default value: NULL