NMSettingVpn: libnm Reference Manual

- - -

NMSettingVpn

NMSettingVpn — Describes connection properties for Virtual Private Networks

Functions

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-void -	-(*NMVpnIterFunc) () -
-NMSetting * -	-nm_setting_vpn_new () -
const char * -	-nm_setting_vpn_get_service_type () -
const char * -	-nm_setting_vpn_get_user_name () -
-gboolean -	-nm_setting_vpn_get_persistent () -
-guint32 -	-nm_setting_vpn_get_num_data_items () -
-void -	-nm_setting_vpn_add_data_item () -
const char * -	-nm_setting_vpn_get_data_item () -
-gboolean -	-nm_setting_vpn_remove_data_item () -
-void -	-nm_setting_vpn_foreach_data_item () -
const char ** -	-nm_setting_vpn_get_data_keys () -
-guint32 -	-nm_setting_vpn_get_num_secrets () -
-void -	-nm_setting_vpn_add_secret () -
const char * -	-nm_setting_vpn_get_secret () -
-gboolean -	-nm_setting_vpn_remove_secret () -
-void -	-nm_setting_vpn_foreach_secret () -
const char ** -	-nm_setting_vpn_get_secret_keys () -
-guint32 -	-nm_setting_vpn_get_timeout () -

Types and Values

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#define	NM_SETTING_VPN_SETTING_NAME
#define	NM_SETTING_VPN_SERVICE_TYPE
#define	NM_SETTING_VPN_USER_NAME
#define	NM_SETTING_VPN_PERSISTENT
#define	NM_SETTING_VPN_DATA
#define	NM_SETTING_VPN_SECRETS
#define	NM_SETTING_VPN_TIMEOUT

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

Since: 1.42, 1.40.4

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

NMSettingVpn — Describes connection properties for Virtual Private Networks

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+void +	+(*NMVpnIterFunc) () +
+NMSetting * +	+nm_setting_vpn_new () +
const char * +	+nm_setting_vpn_get_service_type () +
const char * +	+nm_setting_vpn_get_user_name () +
+gboolean +	+nm_setting_vpn_get_persistent () +
+guint32 +	+nm_setting_vpn_get_num_data_items () +
+void +	+nm_setting_vpn_add_data_item () +
const char * +	+nm_setting_vpn_get_data_item () +
+gboolean +	+nm_setting_vpn_remove_data_item () +
+void +	+nm_setting_vpn_foreach_data_item () +
const char ** +	+nm_setting_vpn_get_data_keys () +
+guint32 +	+nm_setting_vpn_get_num_secrets () +
+void +	+nm_setting_vpn_add_secret () +
const char * +	+nm_setting_vpn_get_secret () +
+gboolean +	+nm_setting_vpn_remove_secret () +
+void +	+nm_setting_vpn_foreach_secret () +
const char ** +	+nm_setting_vpn_get_secret_keys () +
+guint32 +	+nm_setting_vpn_get_timeout () +

Types and Values

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

#define	NM_SETTING_VPN_SETTING_NAME
#define	NM_SETTING_VPN_SERVICE_TYPE
#define	NM_SETTING_VPN_USER_NAME
#define	NM_SETTING_VPN_PERSISTENT
#define	NM_SETTING_VPN_DATA
#define	NM_SETTING_VPN_SECRETS
#define	NM_SETTING_VPN_TIMEOUT

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

Since: 1.42

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"
+