Commit 50df7397 authored by Dan Williams's avatar Dan Williams

docs: document the VPN setting

parent 2a020de9
......@@ -32,6 +32,27 @@
#include "nm-dbus-glib-types.h"
#include "nm-setting-private.h"
/**
* SECTION:nm-setting-vpn
* @short_description: Describes connection properties for Virtual Private Networks
* @include: nm-setting-vpn.h
*
* 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.
**/
/**
* nm_setting_vpn_error_quark:
*
* Registers an error quark for #NMSettingVPN if necessary.
*
* Returns: the error quark used for #NMSettingVPN errors.
**/
GQuark
nm_setting_vpn_error_quark (void)
{
......@@ -108,12 +129,27 @@ enum {
LAST_PROP
};
/**
* nm_setting_vpn_new:
*
* Creates a new #NMSettingVPN object with default values.
*
* Returns: (transfer full): the new empty #NMSettingVPN object
**/
NMSetting *
nm_setting_vpn_new (void)
{
return (NMSetting *) g_object_new (NM_TYPE_SETTING_VPN, NULL);
}
/**
* nm_setting_vpn_get_service_type:
*
* Returns the service name of the VPN, which identifies the specific VPN
* plugin that should be used to connect to this VPN.
*
* Returns: the VPN plugin's service name
**/
const char *
nm_setting_vpn_get_service_type (NMSettingVPN *setting)
{
......@@ -122,6 +158,12 @@ nm_setting_vpn_get_service_type (NMSettingVPN *setting)
return NM_SETTING_VPN_GET_PRIVATE (setting)->service_type;
}
/**
* nm_setting_vpn_get_user_name:
* @setting: the #NMSettingVPN
*
* Returns: the #NMSettingVPN:user-name property of the setting
**/
const char *
nm_setting_vpn_get_user_name (NMSettingVPN *setting)
{
......@@ -130,6 +172,16 @@ nm_setting_vpn_get_user_name (NMSettingVPN *setting)
return NM_SETTING_VPN_GET_PRIVATE (setting)->user_name;
}
/**
* nm_setting_vpn_add_data_item:
* @setting: the #NMSettingVPN
* @key: a name that uniquely identifies the given value @item
* @item: the value to be referenced by @key
*
* 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.
**/
void
nm_setting_vpn_add_data_item (NMSettingVPN *setting,
const char *key,
......@@ -145,6 +197,16 @@ nm_setting_vpn_add_data_item (NMSettingVPN *setting,
g_strdup (key), g_strdup (item));
}
/**
* nm_setting_vpn_get_data_item:
* @setting: the #NMSettingVPN
* @key: the name of the data item to retrieve
*
* Retrieves the data item of a key/value relationship previously established
* by nm_setting_vpn_add_data_item().
*
* Returns: the data item, if any
**/
const char *
nm_setting_vpn_get_data_item (NMSettingVPN *setting, const char *key)
{
......@@ -153,6 +215,14 @@ nm_setting_vpn_get_data_item (NMSettingVPN *setting, const char *key)
return (const char *) g_hash_table_lookup (NM_SETTING_VPN_GET_PRIVATE (setting)->data, key);
}
/**
* nm_setting_vpn_remove_data_item:
* @setting: the #NMSettingVPN
* @key: the name of the data item to remove
*
* Deletes a key/value relationship previously established by
* nm_setting_vpn_add_data_item().
**/
void
nm_setting_vpn_remove_data_item (NMSettingVPN *setting, const char *key)
{
......@@ -212,6 +282,15 @@ nm_setting_vpn_foreach_data_item (NMSettingVPN *setting,
foreach_item_helper (NM_SETTING_VPN_GET_PRIVATE (setting)->data, func, user_data);
}
/**
* nm_setting_vpn_add_secret:
* @setting: the #NMSettingVPN
* @key: a name that uniquely identifies the given secret @secret
* @secret: the secret to be referenced by @key
*
* Establishes a relationship between @key and @secret internally in the
* setting which may be retrieved later.
**/
void
nm_setting_vpn_add_secret (NMSettingVPN *setting,
const char *key,
......@@ -227,6 +306,16 @@ nm_setting_vpn_add_secret (NMSettingVPN *setting,
g_strdup (key), g_strdup (secret));
}
/**
* nm_setting_vpn_get_secret:
* @setting: the #NMSettingVPN
* @key: the name of the secret to retrieve
*
* Retrieves the secret of a key/value relationship previously established
* by nm_setting_vpn_add_secret().
*
* Returns: the secret, if any
**/
const char *
nm_setting_vpn_get_secret (NMSettingVPN *setting, const char *key)
{
......@@ -235,6 +324,14 @@ nm_setting_vpn_get_secret (NMSettingVPN *setting, const char *key)
return (const char *) g_hash_table_lookup (NM_SETTING_VPN_GET_PRIVATE (setting)->secrets, key);
}
/**
* nm_setting_vpn_remove_secret:
* @setting: the #NMSettingVPN
* @key: the name of the secret to remove
*
* Deletes a key/value relationship previously established by
* nm_setting_vpn_add_secret().
**/
void
nm_setting_vpn_remove_secret (NMSettingVPN *setting, const char *key)
{
......
......@@ -39,8 +39,14 @@ G_BEGIN_DECLS
#define NM_SETTING_VPN_SETTING_NAME "vpn"
typedef enum
{
/**
* 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
*/
typedef enum {
NM_SETTING_VPN_ERROR_UNKNOWN = 0,
NM_SETTING_VPN_ERROR_INVALID_PROPERTY,
NM_SETTING_VPN_ERROR_MISSING_PROPERTY,
......@@ -71,6 +77,13 @@ typedef struct {
void (*_reserved4) (void);
} NMSettingVPNClass;
/**
* NMVPNIterFunc:
* @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()
**/
typedef void (*NMVPNIterFunc) (const char *key, const char *value, gpointer user_data);
GType nm_setting_vpn_get_type (void);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment