NMSettingVpn

NMSettingVpn — Describes connection properties for Virtual Private Networks

Properties

GHashTable * data Read / Write
gboolean persistent Read / Write
GHashTable * secrets Read / Write
char * service-type Read / Write
guint timeout Read / Write
char * user-name Read / Write

Object Hierarchy

    GObject
    ╰── NMSetting
        ╰── NMSettingVpn

Description

The NMSettingVpn object is a NMSetting subclass that describes properties necessary for connection to Virtual Private Networks. NetworkManager uses a plugin architecture to allow easier use of new VPN types, and this setting abstracts the configuration for those plugins. Since the configuration options are only known to the VPN plugins themselves, the VPN configuration options are stored as key/value pairs of strings rather than GObject properties.

Functions

NMVpnIterFunc ()

void
(*NMVpnIterFunc) (const char *key,
                  const char *value,
                  gpointer user_data);

Parameters

key

the name of the data or secret item

 

value

the value of the data or secret item

 

user_data

User data passed to nm_setting_vpn_foreach_data_item() or nm_setting_vpn_foreach_secret()

 

nm_setting_vpn_new ()

NMSetting *
nm_setting_vpn_new (void);

Creates a new NMSettingVpn object with default values.

Returns

the new empty NMSettingVpn object.

[transfer full]


nm_setting_vpn_get_service_type ()

const char *
nm_setting_vpn_get_service_type (NMSettingVpn *setting);

Returns the service name of the VPN, which identifies the specific VPN plugin that should be used to connect to this VPN.

Parameters

setting

the NMSettingVpn

 

Returns

the VPN plugin's service name


nm_setting_vpn_get_user_name ()

const char *
nm_setting_vpn_get_user_name (NMSettingVpn *setting);

Parameters

setting

the NMSettingVpn

 

Returns

the “user-name” property of the setting


nm_setting_vpn_get_persistent ()

gboolean
nm_setting_vpn_get_persistent (NMSettingVpn *setting);

Parameters

setting

the NMSettingVpn

 

Returns

the “persistent” property of the setting


nm_setting_vpn_get_num_data_items ()

guint32
nm_setting_vpn_get_num_data_items (NMSettingVpn *setting);

Gets number of key/value pairs of VPN configuration data.

Parameters

setting

the NMSettingVpn

 

Returns

the number of VPN plugin specific configuration data items


nm_setting_vpn_add_data_item ()

void
nm_setting_vpn_add_data_item (NMSettingVpn *setting,
                              const char *key,
                              const char *item);

Establishes a relationship between key and item internally in the setting which may be retrieved later. Should not be used to store passwords or other secrets, which is what nm_setting_vpn_add_secret() is for.

Before 1.24, item must not be NULL and not an empty string. Since 1.24, item can be set to an empty string. It can also be set to NULL to unset the key. In that case, the behavior is as if calling nm_setting_vpn_remove_data_item().

Parameters

setting

the NMSettingVpn

 

key

a name that uniquely identifies the given value item

 

item

the value to be referenced by key .

[allow-none]

nm_setting_vpn_get_data_item ()

const char *
nm_setting_vpn_get_data_item (NMSettingVpn *setting,
                              const char *key);

Retrieves the data item of a key/value relationship previously established by nm_setting_vpn_add_data_item().

Parameters

setting

the NMSettingVpn

 

key

the name of the data item to retrieve

 

Returns

the data item, if any


nm_setting_vpn_remove_data_item ()

gboolean
nm_setting_vpn_remove_data_item (NMSettingVpn *setting,
                                 const char *key);

Deletes a key/value relationship previously established by nm_setting_vpn_add_data_item().

Parameters

setting

the NMSettingVpn

 

key

the name of the data item to remove

 

Returns

TRUE if the data item was found and removed from the internal list, FALSE if it was not.


nm_setting_vpn_foreach_data_item ()

void
nm_setting_vpn_foreach_data_item (NMSettingVpn *setting,
                                  NMVpnIterFunc func,
                                  gpointer user_data);

Iterates all data items stored in this setting. It is safe to add, remove, and modify data items inside func , though any additions or removals made during iteration will not be part of the iteration.

Parameters

setting

a NMSettingVpn

 

func

an user provided function.

[scope call]

user_data

data to be passed to func

 

nm_setting_vpn_get_data_keys ()

const char **
nm_setting_vpn_get_data_keys (NMSettingVpn *setting,
                              guint *out_length);

Retrieves every data key inside setting , as an array.

Parameters

setting

the NMSettingVpn

 

out_length

the length of the returned array.

[allow-none][out]

Returns

a NULL-terminated array containing each data key or NULL if there are no data items.

[array length=out_length][transfer container]

Since: 1.12


nm_setting_vpn_get_num_secrets ()

guint32
nm_setting_vpn_get_num_secrets (NMSettingVpn *setting);

Gets number of VPN plugin specific secrets in the setting.

Parameters

setting

the NMSettingVpn

 

Returns

the number of VPN plugin specific secrets


nm_setting_vpn_add_secret ()

void
nm_setting_vpn_add_secret (NMSettingVpn *setting,
                           const char *key,
                           const char *secret);

Establishes a relationship between key and secret internally in the setting which may be retrieved later.

Before 1.24, secret must not be NULL and not an empty string. Since 1.24, secret can be set to an empty string. It can also be set to NULL to unset the key. In that case, the behavior is as if calling nm_setting_vpn_remove_secret().

Parameters

setting

the NMSettingVpn

 

key

a name that uniquely identifies the given secret secret

 

secret

the secret to be referenced by key .

[allow-none]

nm_setting_vpn_get_secret ()

const char *
nm_setting_vpn_get_secret (NMSettingVpn *setting,
                           const char *key);

Retrieves the secret of a key/value relationship previously established by nm_setting_vpn_add_secret().

Parameters

setting

the NMSettingVpn

 

key

the name of the secret to retrieve

 

Returns

the secret, if any


nm_setting_vpn_remove_secret ()

gboolean
nm_setting_vpn_remove_secret (NMSettingVpn *setting,
                              const char *key);

Deletes a key/value relationship previously established by nm_setting_vpn_add_secret().

Parameters

setting

the NMSettingVpn

 

key

the name of the secret to remove

 

Returns

TRUE if the secret was found and removed from the internal list, FALSE if it was not.


nm_setting_vpn_foreach_secret ()

void
nm_setting_vpn_foreach_secret (NMSettingVpn *setting,
                               NMVpnIterFunc func,
                               gpointer user_data);

Iterates all secrets stored in this setting. It is safe to add, remove, and modify secrets inside func , though any additions or removals made during iteration will not be part of the iteration.

Parameters

setting

a NMSettingVpn

 

func

an user provided function.

[scope call]

user_data

data to be passed to func

 

nm_setting_vpn_get_secret_keys ()

const char **
nm_setting_vpn_get_secret_keys (NMSettingVpn *setting,
                                guint *out_length);

Retrieves every secret key inside setting , as an array.

Parameters

setting

the NMSettingVpn

 

out_length

the length of the returned array.

[allow-none][out]

Returns

a NULL-terminated array containing each secret key or NULL if there are no secrets.

[array length=out_length][transfer container]

Since: 1.12


nm_setting_vpn_get_timeout ()

guint32
nm_setting_vpn_get_timeout (NMSettingVpn *setting);

Parameters

setting

the NMSettingVpn

 

Returns

the “timeout” property of the setting

Since: 1.2

Types and Values

NM_SETTING_VPN_SETTING_NAME

#define NM_SETTING_VPN_SETTING_NAME "vpn"

NM_SETTING_VPN_SERVICE_TYPE

#define NM_SETTING_VPN_SERVICE_TYPE "service-type"

NM_SETTING_VPN_USER_NAME

#define NM_SETTING_VPN_USER_NAME    "user-name"

NM_SETTING_VPN_PERSISTENT

#define NM_SETTING_VPN_PERSISTENT   "persistent"

NM_SETTING_VPN_DATA

#define NM_SETTING_VPN_DATA         "data"

NM_SETTING_VPN_SECRETS

#define NM_SETTING_VPN_SECRETS      "secrets"

NM_SETTING_VPN_TIMEOUT

#define NM_SETTING_VPN_TIMEOUT      "timeout"

NMSettingVpn

typedef struct _NMSettingVpn NMSettingVpn;

VPN Settings

Property Details

The “data” property

  “data”                     GHashTable *

Owner: NMSettingVpn

Flags: Read / Write


The “persistent” property

  “persistent”               gboolean

If the VPN service supports persistence, and this property is TRUE, the VPN will attempt to stay connected across link changes and outages, until explicitly disconnected.

Owner: NMSettingVpn

Flags: Read / Write

Default value: FALSE


The “secrets” property

  “secrets”                  GHashTable *

Owner: NMSettingVpn

Flags: Read / Write


The “service-type” property

  “service-type”             char *

D-Bus service name of the VPN plugin that this setting uses to connect to its network. i.e. org.freedesktop.NetworkManager.vpnc for the vpnc plugin.

Owner: NMSettingVpn

Flags: Read / Write

Default value: NULL


The “timeout” property

  “timeout”                  guint

Timeout for the VPN service to establish the connection. Some services may take quite a long time to connect. Value of 0 means a default timeout, which is 60 seconds (unless overridden by vpn.timeout in configuration file). Values greater than zero mean timeout in seconds.

Owner: NMSettingVpn

Flags: Read / Write

Default value: 0

Since: 1.2


The “user-name” property

  “user-name”                char *

If the VPN connection requires a user name for authentication, that name should be provided here. If the connection is available to more than one user, and the VPN requires each user to supply a different name, then leave this property empty. If this property is empty, NetworkManager will automatically supply the username of the user which requested the VPN connection.

Owner: NMSettingVpn

Flags: Read / Write

Default value: NULL