NMSettingConnection

NMSettingConnection — Describes general connection properties

Synopsis

#include <nm-setting-connection.h>

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

Object Hierarchy

  GObject
   +----NMSetting
         +----NMSettingConnection
  GEnum
   +----NMSettingConnectionError

Properties

  "autoconnect"              gboolean              : Read / Write / Construct
  "id"                       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

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;


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_AUTOCONNECT

#define NM_SETTING_CONNECTION_AUTOCONNECT "autoconnect"


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_MASTER

#define NM_SETTING_CONNECTION_MASTER      "master"


NM_SETTING_CONNECTION_PERMISSIONS

#define NM_SETTING_CONNECTION_PERMISSIONS "permissions"


NM_SETTING_CONNECTION_READ_ONLY

#define NM_SETTING_CONNECTION_READ_ONLY   "read-only"


NM_SETTING_CONNECTION_SECONDARIES

#define NM_SETTING_CONNECTION_SECONDARIES "secondaries"


NM_SETTING_CONNECTION_SETTING_NAME

#define NM_SETTING_CONNECTION_SETTING_NAME "connection"


NM_SETTING_CONNECTION_SLAVE_TYPE

#define NM_SETTING_CONNECTION_SLAVE_TYPE  "slave-type"


NM_SETTING_CONNECTION_TIMESTAMP

#define NM_SETTING_CONNECTION_TIMESTAMP   "timestamp"


NM_SETTING_CONNECTION_TYPE

#define NM_SETTING_CONNECTION_TYPE        "type"


NM_SETTING_CONNECTION_UUID

#define NM_SETTING_CONNECTION_UUID        "uuid"


NM_SETTING_CONNECTION_ZONE

#define NM_SETTING_CONNECTION_ZONE        "zone"


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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_new ()

NMSetting *         nm_setting_connection_new           (void);

Creates a new NMSettingConnection object with default values.

Returns :

the new empty NMSettingConnection object

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

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. Defaults to TRUE.

Default value: TRUE


The "id" property

  "id"                       gchar*                : Read / Write

A human readable unique idenfier for the connection, like "Work WiFi" or "T-Mobile 3G".

Default value: NULL


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

TRUE if the connection can be modified using the providing settings service's D-Bus interface with the right privileges, or FALSE 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.

Since 0.9.8


The "slave-type" property

  "slave-type"               gchar*                : Read / Write

Setting name describing the type of slave device (ie 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.

Default value: 0


The "type" property

  "type"                     gchar*                : Read / Write

The general hardware type of the device used for the network connection, contains the name of the NMSetting object that describes that hardware type's parameters. For example, for WiFi devices, the name of the NMSettingWireless setting.

Default value: NULL


The "uuid" property

  "uuid"                     gchar*                : Read / Write

A universally unique idenfier for the connection, for example generated with libuuid. Should be assigned when the connection is created, and never changed as long as the connection still applies to the same network. For example, should not be changed when the "id" or NMSettingIP4Config changes, but might need to be re-created when the WiFi SSID, mobile broadband network provider, or "type" 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