NMSettingConnection

NMSettingConnection — Describes general connection properties

Properties

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

Object Hierarchy

    GEnum
    ╰── NMSettingConnectionError
    GObject
    ╰── NMSetting
        ╰── NMSettingConnection

Includes

#include <nm-setting-connection.h>

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.

Functions

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_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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 entries in the “permissions” property of this setting.

Parameters

setting

the NMSettingConnection

 

Returns

the number of permissions entries


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.

Parameters

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 according 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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

Parameters

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

Parameters

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 connection UUID to the setting.

Parameters

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 .

Parameters

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 .

Parameters

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

Parameters

setting

the NMSettingConnection

 

Returns

the value contained in the “gateway-ping-timeout” property.

Since: 0.9.10

Types and Values

NM_SETTING_CONNECTION_SETTING_NAME

#define NM_SETTING_CONNECTION_SETTING_NAME "connection"

enum NMSettingConnectionError

Describes errors that may result from operations involving a NMSettingConnection.

Members

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_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.

Property Details

The “autoconnect” property

  “autoconnect”              gboolean

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.

Owner: NMSettingConnection

Flags: Read / Write / Construct

Default value: TRUE


The “gateway-ping-timeout” property

  “gateway-ping-timeout”     guint

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

Owner: NMSettingConnection

Flags: Read / Write / Construct

Allowed values: <= 30

Default value: 0

Since: 0.9.10


The “id” property

  “id”                       gchar *

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

Owner: NMSettingConnection

Flags: Read / Write

Default value: NULL


The “interface-name” property

  “interface-name”           gchar *

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 software devices this specifies the name of the created device.

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.

Owner: NMSettingConnection

Flags: Read / Write

Default value: NULL

Since: 0.9.10


The “master” property

  “master”                   gchar *

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

Owner: NMSettingConnection

Flags: Read / Write

Default value: NULL


The “permissions” property

  “permissions”              GSList_gchararray_ *

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.

Owner: NMSettingConnection

Flags: Read / Write


The “read-only” property

  “read-only”                gboolean

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.

Owner: NMSettingConnection

Flags: Read / Write / Construct

Default value: FALSE


The “secondaries” property

  “secondaries”              GSList_gchararray_ *

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

Owner: NMSettingConnection

Flags: Read / Write

Since: 0.9.8


The “slave-type” property

  “slave-type”               gchar *

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.

Owner: NMSettingConnection

Flags: Read / Write

Default value: NULL


The “timestamp” property

  “timestamp”                guint64

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

Owner: NMSettingConnection

Flags: Read / Write / Construct

Default value: 0


The “type” property

  “type”                     gchar *

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

Owner: NMSettingConnection

Flags: Read / Write

Default value: NULL


The “uuid” property

  “uuid”                     gchar *

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

Owner: NMSettingConnection

Flags: Read / Write

Default value: NULL


The “zone” property

  “zone”                     gchar *

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.

Owner: NMSettingConnection

Flags: Read / Write / Construct

Default value: NULL