## NMSettingVPN NMSettingVPN — Describes connection properties for Virtual Private Networks |

## Synopsis

    #include <nm-setting-vpn.h>

    #define             NM_SETTING_VPN_SETTING_NAME
    enum                NMSettingVpnError;
    #define             NM_SETTING_VPN_ERROR
    GQuark              nm_setting_vpn_error_quark          (void);
    #define             NM_SETTING_VPN_SERVICE_TYPE
    #define             NM_SETTING_VPN_USER_NAME
    #define             NM_SETTING_VPN_DATA
    #define             NM_SETTING_VPN_SECRETS
                        NMSettingVPN;
                        NMSettingVPNClass;
    void                (*NMVPNIterFunc)                    (const char *key,
                                                             const char *value,
                                                             gpointer user_data);
    NMSetting *         nm_setting_vpn_new                  (void);
    const char *        nm_setting_vpn_get_service_type     (NMSettingVPN *setting);
    const char *        nm_setting_vpn_get_user_name        (NMSettingVPN *setting);
    guint32             nm_setting_vpn_get_num_data_items   (NMSettingVPN *setting);
    void                nm_setting_vpn_add_data_item        (NMSettingVPN *setting,
                                                             const char *key,
                                                             const char *item);
    const char *        nm_setting_vpn_get_data_item        (NMSettingVPN *setting,
                                                             const char *key);
    gboolean            nm_setting_vpn_remove_data_item     (NMSettingVPN *setting,
                                                             const char *key);
    void                nm_setting_vpn_foreach_data_item    (NMSettingVPN *setting,
                                                             NMVPNIterFunc func,
                                                             gpointer user_data);
    guint32             nm_setting_vpn_get_num_secrets      (NMSettingVPN *setting);
    void                nm_setting_vpn_add_secret           (NMSettingVPN *setting,
                                                             const char *key,
                                                             const char *secret);
    const char *        nm_setting_vpn_get_secret           (NMSettingVPN *setting,
                                                             const char *key);
    gboolean            nm_setting_vpn_remove_secret        (NMSettingVPN *setting,
                                                             const char *key);
    void                nm_setting_vpn_foreach_secret       (NMSettingVPN *setting,
                                                             NMVPNIterFunc func,
                                                             gpointer user_data);

## Object Hierarchy

      GEnum
       +----NMSettingVpnError

      GObject
       +----NMSetting
             +----NMSettingVPN

## Properties

      "data"                     GHashTable_gchararray+gchararray_*  : Read / Write
      "secrets"                  GHashTable_gchararray+gchararray_*  : Read / Write
      "service-type"             gchar*                : Read / Write
      "user-name"                gchar*                : Read / Write

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

## Details

### NM_SETTING_VPN_SETTING_NAME

    #define NM_SETTING_VPN_SETTING_NAME "vpn"

### enum NMSettingVpnError

    typedef enum {
    	NM_SETTING_VPN_ERROR_UNKNOWN = 0,      /*< nick=UnknownError >*/
    	NM_SETTING_VPN_ERROR_INVALID_PROPERTY, /*< nick=InvalidProperty >*/
    	NM_SETTING_VPN_ERROR_MISSING_PROPERTY, /*< nick=MissingProperty >*/
    } NMSettingVpnError;

`NM_SETTING_VPN_ERROR_UNKNOWN` | unknown or unclassified error
`NM_SETTING_VPN_ERROR_INVALID_PROPERTY` | the property was invalid
`NM_SETTING_VPN_ERROR_MISSING_PROPERTY` | the property was missing and is required

### NM_SETTING_VPN_ERROR

    #define NM_SETTING_VPN_ERROR nm_setting_vpn_error_quark ()

### nm_setting_vpn_error_quark ()

    GQuark              nm_setting_vpn_error_quark          (void);

Registers an error quark for NMSettingVPN if necessary.

Returns : | the error quark used for NMSettingVPN errors.

### 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_DATA

    #define NM_SETTING_VPN_DATA         "data"

### NM_SETTING_VPN_SECRETS

    #define NM_SETTING_VPN_SECRETS      "secrets"

### NMSettingVPN

    typedef struct _NMSettingVPN NMSettingVPN;

### NMSettingVPNClass

    typedef struct {
    	NMSettingClass parent;

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

### NMVPNIterFunc ()

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

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

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

`setting` : | the NMSettingVPN
Returns : | the "user-name" 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.

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

`setting` : | the NMSettingVPN
`key` : | a name that uniquely identifies the given value `item`
`item` : | the value to be referenced by `key`

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

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

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

`setting` : | a NMSettingVPN
`func` : | an user provided function. [scope call]
`user_data` : | data to be passed to `func`

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

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

`setting` : | the NMSettingVPN
`key` : | a name that uniquely identifies the given secret `secret`
`secret` : | the secret to be referenced by `key`

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

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

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

`setting` : | a NMSettingVPN
`func` : | an user provided function. [scope call]
`user_data` : | data to be passed to `func`

## Property Details

### The `"data"` property

      "data"                     GHashTable_gchararray+gchararray_*  : Read / Write

Dictionary of key/value pairs of VPN plugin specific data. Both keys and values must be strings.

### The `"secrets"` property

      "secrets"                  GHashTable_gchararray+gchararray_*  : Read / Write

Dictionary of key/value pairs of VPN plugin specific secrets like passwords or private keys. Both keys and values must be strings.

### The `"service-type"` property

      "service-type"             gchar*                : Read / Write

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.

Default value: NULL

### The `"user-name"` property

      "user-name"                gchar*                : Read / Write

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.

Default value: NULL