NMVpnPluginInfo: libnm Reference Manual

## NMVpnPluginInfo NMVpnPluginInfo |

## Functions

NMVpnPluginInfo * | nm_vpn_plugin_info_new_from_file ()
NMVpnPluginInfo * | nm_vpn_plugin_info_new_with_data ()
NMVpnPluginInfo * | nm_vpn_plugin_info_new_search_file ()
const char * | nm_vpn_plugin_info_get_name ()
const char * | nm_vpn_plugin_info_get_filename ()
const char * | nm_vpn_plugin_info_get_service ()
const char * | nm_vpn_plugin_info_get_plugin ()
const char * | nm_vpn_plugin_info_get_program ()
const char * | nm_vpn_plugin_info_get_auth_dialog ()
gboolean | nm_vpn_plugin_info_supports_hints ()
gboolean | nm_vpn_plugin_info_supports_multiple ()
const char *const* | nm_vpn_plugin_info_get_aliases ()
const char * | nm_vpn_plugin_info_lookup_property ()
gboolean | nm_vpn_plugin_info_validate_filename ()
GSList * | nm_vpn_plugin_info_list_load ()
gboolean | nm_vpn_plugin_info_list_add ()
gboolean | nm_vpn_plugin_info_list_remove ()
NMVpnPluginInfo * | nm_vpn_plugin_info_list_find_by_name ()
NMVpnPluginInfo * | nm_vpn_plugin_info_list_find_by_filename ()
NMVpnPluginInfo * | nm_vpn_plugin_info_list_find_by_service ()
char * | nm_vpn_plugin_info_list_find_service_type ()
char ** | nm_vpn_plugin_info_list_get_service_types ()
NMVpnEditorPlugin * | nm_vpn_plugin_info_get_editor_plugin ()
void | nm_vpn_plugin_info_set_editor_plugin ()
NMVpnEditorPlugin * | nm_vpn_plugin_info_load_editor_plugin ()

## Properties

gchar * | filename | Read / Write / Construct Only
GKeyFile * | keyfile | Write / Construct Only
gchar * | name | Read

## Types and Values

#define | NM_VPN_PLUGIN_INFO_NAME
#define | NM_VPN_PLUGIN_INFO_FILENAME
#define | NM_VPN_PLUGIN_INFO_KEYFILE
#define | NM_VPN_PLUGIN_INFO_KF_GROUP_CONNECTION
#define | NM_VPN_PLUGIN_INFO_KF_GROUP_LIBNM
#define | NM_VPN_PLUGIN_INFO_KF_GROUP_GNOME
| NMVpnPluginInfo

## Object Hierarchy

        GObject
        ╰── NMVpnPluginInfo

## Implemented Interfaces

NMVpnPluginInfo implements GInitable.

## Description

## Functions

### nm_vpn_plugin_info_new_from_file ()

    NMVpnPluginInfo *
    nm_vpn_plugin_info_new_from_file (const char *filename,
                                      GError **error);

Read the plugin info from file `filename` . Does not do any further verification on the file. You might want to check file permissions and ownership of the file.

#### Parameters

filename | filename to read. |
error | on failure, the error reason. |

#### Returns

`NULL` if there is any error or a newly created NMVpnPluginInfo instance.

Since: 1.2

### nm_vpn_plugin_info_new_with_data ()

    NMVpnPluginInfo *
    nm_vpn_plugin_info_new_with_data (const char *filename,
                                      GKeyFile *keyfile,
                                      GError **error);

This constructor does not read any data from file but takes instead a `keyfile` argument.

#### Parameters

filename | optional filename. |
keyfile | inject data for the plugin info instance. |
error | construction may fail if the keyfile lacks mandatory fields. In this case, return the error reason. |

#### Returns

new plugin info instance.

Since: 1.2

### nm_vpn_plugin_info_new_search_file ()

    NMVpnPluginInfo *
    nm_vpn_plugin_info_new_search_file (const char *name,
                                        const char *service);

This has the same effect as doing a full `nm_vpn_plugin_info_list_load()` followed by a search for the first matching VPN plugin info that has the given `name` and/or `service` .

#### Parameters

name | the name to search for. Either `name` or `service` must be present. | [allow-none]
service | the service to search for. Either `name` or `service` must be present. | [allow-none]

#### Returns

a newly created instance of plugin info or `NULL` if no matching value was found.

[transfer full]

Since: 1.4

### nm_vpn_plugin_info_get_name ()

    const char *
    nm_vpn_plugin_info_get_name (NMVpnPluginInfo *self);

#### Parameters

self | plugin info instance |

#### Returns

the name. Cannot be `NULL`.

[transfer none]

Since: 1.2

### nm_vpn_plugin_info_get_filename ()

    const char *
    nm_vpn_plugin_info_get_filename (NMVpnPluginInfo *self);

#### Parameters

self | plugin info instance |

#### Returns

the filename. Can be `NULL`.

[transfer none]

Since: 1.2

### nm_vpn_plugin_info_get_service ()

    const char *
    nm_vpn_plugin_info_get_service (NMVpnPluginInfo *self);

#### Parameters

self | plugin info instance |

#### Returns

the service. Cannot be `NULL`.

[transfer none]

Since: 1.4

### nm_vpn_plugin_info_get_plugin ()

    const char *
    nm_vpn_plugin_info_get_plugin (NMVpnPluginInfo *self);

#### Parameters

self | plugin info instance |

#### Returns

the plugin. Can be `NULL`.

[transfer none]

Since: 1.2

### nm_vpn_plugin_info_get_program ()

    const char *
    nm_vpn_plugin_info_get_program (NMVpnPluginInfo *self);

#### Parameters

self | plugin info instance |

#### Returns

the program. Can be `NULL`.

[transfer none]

Since: 1.2

### nm_vpn_plugin_info_get_auth_dialog ()

    const char *
    nm_vpn_plugin_info_get_auth_dialog (NMVpnPluginInfo *self);

#### Parameters

self | plugin info instance |

#### Returns

the absolute path to the auth-dialog helper or `NULL`.

Since: 1.4

### nm_vpn_plugin_info_supports_hints ()

    gboolean
    nm_vpn_plugin_info_supports_hints (NMVpnPluginInfo *self);

#### Parameters

self | plugin info instance |

#### Returns

`TRUE` if the supports hints for secret requests, otherwise `FALSE`

Since: 1.4

### nm_vpn_plugin_info_supports_multiple ()

    gboolean
    nm_vpn_plugin_info_supports_multiple (NMVpnPluginInfo *self);

#### Parameters

self | plugin info instance |

#### Returns

`TRUE` if the service supports multiple instances with different bus names, otherwise `FALSE`

Since: 1.2

### nm_vpn_plugin_info_get_aliases ()

    const char *const*
    nm_vpn_plugin_info_get_aliases (NMVpnPluginInfo *self);

#### Parameters

self | plugin info instance |

#### Returns

the aliases from the name-file.

[array zero-terminated=1][element-type utf8][transfer none]

Since: 1.4

### nm_vpn_plugin_info_lookup_property ()

    const char *
    nm_vpn_plugin_info_lookup_property (NMVpnPluginInfo *self,
                                        const char *group,
                                        const char *key);

#### Parameters

self | plugin info instance |
group | group name |
key | name of the property |

#### Returns

NMVpnPluginInfo is internally a GKeyFile. Returns the matching property.

[transfer none]

Since: 1.2

### nm_vpn_plugin_info_validate_filename ()

    gboolean
    nm_vpn_plugin_info_validate_filename (const char *filename);

Regular name files have a certain pattern. That basically means they have the file extension "name". Check if `filename` is valid according to that pattern.

#### Parameters

filename | the filename to check |

Since: 1.2

### nm_vpn_plugin_info_list_load ()

    GSList *
    nm_vpn_plugin_info_list_load (void);

#### Returns

list of plugins loaded from the default directories rejecting duplicates.

[element-type NMVpnPluginInfo][transfer full]

Since: 1.2

### nm_vpn_plugin_info_list_add ()

    gboolean
    nm_vpn_plugin_info_list_add (GSList **list,
                                 NMVpnPluginInfo *plugin_info,
                                 GError **error);

#### Parameters

list | list of plugins. | [element-type NMVpnPluginInfo]
plugin_info | instance to add |
error | failure reason |

#### Returns

`TRUE` if the plugin was added to `list` . This will fail to add duplicate plugins.

Since: 1.2

### nm_vpn_plugin_info_list_remove ()

    gboolean
    nm_vpn_plugin_info_list_remove (GSList **list,
                                    NMVpnPluginInfo *plugin_info);

Remove `plugin_info` from `list` .

#### Parameters

list | list of plugins. | [element-type NMVpnPluginInfo]
plugin_info | instance |

#### Returns

`TRUE` if `plugin_info` was in `list` and successfully removed.

Since: 1.2

### nm_vpn_plugin_info_list_find_by_name ()

    NMVpnPluginInfo *
    nm_vpn_plugin_info_list_find_by_name (GSList *list,
                                          const char *name);

#### Parameters

list | list of plugins. | [element-type NMVpnPluginInfo]
name | name to search |

#### Returns

the first plugin with a matching `name` (or `NULL`).

[transfer none]

Since: 1.2

### nm_vpn_plugin_info_list_find_by_filename ()

    NMVpnPluginInfo *
    nm_vpn_plugin_info_list_find_by_filename
                                   (GSList *list,
                                    const char *filename);

#### Parameters

list | list of plugins. | [element-type NMVpnPluginInfo]
filename | filename to search |

#### Returns

the first plugin with a matching `filename` (or `NULL`).

[transfer none]

Since: 1.2

### nm_vpn_plugin_info_list_find_by_service ()

    NMVpnPluginInfo *
    nm_vpn_plugin_info_list_find_by_service
                                   (GSList *list,
                                    const char *service);

#### Parameters

list | list of plugins. | [element-type NMVpnPluginInfo]
service | service to search. This can be the main service-type or one of the provided aliases. |

#### Returns

the first plugin with a matching `service` (or `NULL`).

[transfer none]

Since: 1.2

### nm_vpn_plugin_info_list_find_service_type ()

    char *
    nm_vpn_plugin_info_list_find_service_type
                                   (GSList *list,
                                    const char *name);

A VPN plugin provides one or several service-types, like org.freedesktop.NetworkManager.libreswan Certain plugins provide more then one service type, via aliases (org.freedesktop.NetworkManager.openswan). This function looks up a service-type (or an alias) based on a name.

Preferably, the name can be a full service-type/alias of an installed plugin. Otherwise, it can be the name of a VPN plugin (in which case, the primary, non-aliased service-type is returned). Otherwise, it can be one of several well known short-names (which is a hard-coded list of types in libnm). On success, this returns a full qualified service-type (or an alias). It doesn't say, that such an plugin is actually available, but it could be retrieved via `nm_vpn_plugin_info_list_find_by_service()`.

#### Parameters

list | a possibly empty GSList of NMVpnPluginInfo instances. | [element-type NMVpnPluginInfo]
name | a name to lookup the service-type. |

#### Returns

the resolved service-type or `NULL` on failure.

[transfer full]

Since: 1.4

### nm_vpn_plugin_info_list_get_service_types ()

    char **
    nm_vpn_plugin_info_list_get_service_types
                                   (GSList *list,
                                    gboolean only_existing,
                                    gboolean with_abbreviations);

#### Parameters

list | a possibly empty GSList of NMVpnPluginInfo. | [element-type NMVpnPluginInfo]
only_existing | only include results that are actually in `list` . Otherwise, the result is extended with a hard-code list or well-known plugins |
with_abbreviations | if `FALSE`, only full service types are returned. Otherwise, this also includes abbreviated names that can be used with `nm_vpn_plugin_info_list_find_service_type()`. |

#### Returns

a `NULL` terminated strv list of strings. The list itself and the values must be freed with `g_strfreev()`.

[transfer full]

Since: 1.4

### nm_vpn_plugin_info_get_editor_plugin ()

    NMVpnEditorPlugin *
    nm_vpn_plugin_info_get_editor_plugin (NMVpnPluginInfo *self);

#### Parameters

self | plugin info instance |

#### Returns

the cached NMVpnEditorPlugin instance.

[transfer none]

Since: 1.2

### nm_vpn_plugin_info_set_editor_plugin ()

    void
    nm_vpn_plugin_info_set_editor_plugin (NMVpnPluginInfo *self,
                                          NMVpnEditorPlugin *plugin);

Set the internal plugin instance. If `NULL`, only clear the previous instance.

#### Parameters

self | plugin info instance |
plugin | plugin instance. | [allow-none]

Since: 1.2

### nm_vpn_plugin_info_load_editor_plugin ()

    NMVpnEditorPlugin *
    nm_vpn_plugin_info_load_editor_plugin (NMVpnPluginInfo *self,
                                           GError **error);

#### Parameters

self | plugin info instance |
error | error reason on failure |

#### Returns

loads the plugin and returns the newly created instance. The plugin is owned by `self` and can be later retrieved again via `nm_vpn_plugin_info_get_editor_plugin()`. You can load the plugin only once, unless you reset the state via `nm_vpn_plugin_info_set_editor_plugin()`.

[transfer none]

Since: 1.2

## Types and Values

### NM_VPN_PLUGIN_INFO_NAME

    #define NM_VPN_PLUGIN_INFO_NAME        "name"

### NM_VPN_PLUGIN_INFO_FILENAME

    #define NM_VPN_PLUGIN_INFO_FILENAME    "filename"

### NM_VPN_PLUGIN_INFO_KEYFILE

    #define NM_VPN_PLUGIN_INFO_KEYFILE     "keyfile"

### NM_VPN_PLUGIN_INFO_KF_GROUP_CONNECTION

    #define NM_VPN_PLUGIN_INFO_KF_GROUP_CONNECTION   "VPN Connection"

### NM_VPN_PLUGIN_INFO_KF_GROUP_LIBNM

    #define NM_VPN_PLUGIN_INFO_KF_GROUP_LIBNM        "libnm"

### NM_VPN_PLUGIN_INFO_KF_GROUP_GNOME

    #define NM_VPN_PLUGIN_INFO_KF_GROUP_GNOME        "GNOME"

### NMVpnPluginInfo

    typedef struct _NMVpnPluginInfo NMVpnPluginInfo;

## Property Details

### The `“filename”` property

      “filename”                 gchar *

The filename from which the info was loaded. Can be `NULL` if the instance was not loaded from a file (i.e. the keyfile instance was passed to the constructor).

Owner: NMVpnPluginInfo

Flags: Read / Write / Construct Only

Default value: NULL

Since: 1.2

### The `“keyfile”` property

      “keyfile”                  GKeyFile *

Initialize the instance with a different keyfile instance. When passing a keyfile instance, the constructor will not try to read from filename.

Owner: NMVpnPluginInfo

Flags: Write / Construct Only

Since: 1.2

### The `“name”` property

      “name”                     gchar *

The name of the VPN plugin.

Owner: NMVpnPluginInfo

Flags: Read

Default value: NULL

Since: 1.2