NMVpnEditorPlugin: libnm Reference Manual

- - -

NMVpnEditorPlugin

Functions

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

-NMVpnEditorPlugin * -	-(*NMVpnEditorPluginFactory) () -
-NMVpnEditorPlugin * -	-nm_vpn_editor_plugin_factory () -
-NMVpnEditor * -	-nm_vpn_editor_plugin_get_editor () -
-NMVpnEditorPluginCapability -	-nm_vpn_editor_plugin_get_capabilities () -
-gsize -	-nm_vpn_editor_plugin_get_vt () -
-NMConnection * -	-nm_vpn_editor_plugin_import () -
-gboolean -	-nm_vpn_editor_plugin_export () -
-char * -	-nm_vpn_editor_plugin_get_suggested_filename () -
-NMVpnEditorPlugin * -	-nm_vpn_editor_plugin_load_from_file () -
-NMVpnEditorPlugin * -	-nm_vpn_editor_plugin_load () -
-NMVpnPluginInfo * -	-nm_vpn_editor_plugin_get_plugin_info () -
-void -	-nm_vpn_editor_plugin_set_plugin_info () -

Properties

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

-char *	filename	Read / Write / Construct Only
-GKeyFile *	keyfile	Write / Construct Only
-char *	name	Read
-char *	description	Read
-char *	name	Read
-char *	service	Read

Signals

----- - - - - - -

void

changed

Run First

Types and Values

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

enum	NMVpnEditorPluginCapability
#define	NM_VPN_EDITOR_PLUGIN_NAME
#define	NM_VPN_EDITOR_PLUGIN_DESCRIPTION
#define	NM_VPN_EDITOR_PLUGIN_SERVICE
	NMVpnEditorPluginInterface
	NMVpnEditor
	NMVpnEditorPluginVT
	NMVpnPluginInfo

Object Hierarchy

    GFlags
-    ╰── NMVpnEditorPluginCapability
-    GInterface
-    ├── NMVpnEditor
-    ╰── NMVpnEditorPlugin
-    GObject
-    ╰── NMVpnPluginInfo
-

Prerequisites

-NMVpnEditor requires - GObject.

Implemented Interfaces

-NMVpnPluginInfo implements - GInitable.

Description

Functions

NMVpnEditorPluginFactory ()

NMVpnEditorPlugin *
-(*NMVpnEditorPluginFactory) (GError **error);

nm_vpn_editor_plugin_factory ()

NMVpnEditorPlugin *
-nm_vpn_editor_plugin_factory (GError **error);

nm_vpn_editor_plugin_get_editor ()

NMVpnEditor *
-nm_vpn_editor_plugin_get_editor (NMVpnEditorPlugin *plugin,
-                                 NMConnection *connection,
-                                 GError **error);

Parameters

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

plugin	the NMVpnEditorPlugin
connection	the NMConnection to be edited
error	on return, an error or `NULL`

Returns

a new NMVpnEditor or NULL on error.

[transfer full]

nm_vpn_editor_plugin_get_capabilities ()

NMVpnEditorPluginCapability
-nm_vpn_editor_plugin_get_capabilities (NMVpnEditorPlugin *plugin);

nm_vpn_editor_plugin_get_vt ()

gsize
-nm_vpn_editor_plugin_get_vt (NMVpnEditorPlugin *plugin,
-                             NMVpnEditorPluginVT *vt,
-                             gsize vt_size);

Returns an opaque VT function table for the plugin to extend -functionality. The actual meaning of NMVpnEditorPluginVT is not -defined in public API of libnm, instead it must be agreed by -both the plugin and the caller. See the header-only file -'nm-vpn-editor-plugin-call.h' which defines the meaning.

Parameters

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

plugin	the NMVpnEditorPlugin
vt	buffer to be filled with the VT table of the plugin.	[out]
vt_size	the size of the buffer. Can be 0 to only query the -size of plugin's VT.

Returns

the actual size of the plugin -'s virtual function table.

Since: 1.4

nm_vpn_editor_plugin_import ()

NMConnection *
-nm_vpn_editor_plugin_import (NMVpnEditorPlugin *plugin,
-                             const char *path,
-                             GError **error);

Parameters

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

plugin	the NMVpnEditorPlugin
path	full path to the file to attempt to read into a new NMConnection
error	on return, an error or `NULL`

Returns

a new NMConnection imported from path -, or NULL -on error or if the file at path -was not recognized by this plugin.

[transfer full]

nm_vpn_editor_plugin_export ()

gboolean
-nm_vpn_editor_plugin_export (NMVpnEditorPlugin *plugin,
-                             const char *path,
-                             NMConnection *connection,
-                             GError **error);

nm_vpn_editor_plugin_get_suggested_filename ()

char *
-nm_vpn_editor_plugin_get_suggested_filename
-                               (NMVpnEditorPlugin *plugin,
-                                NMConnection *connection);

nm_vpn_editor_plugin_load_from_file ()

NMVpnEditorPlugin *
-nm_vpn_editor_plugin_load_from_file (const char *plugin_name,
-                                     const char *check_service,
-                                     int check_owner,
-                                     NMUtilsCheckFilePredicate check_file,
-                                     gpointer user_data,
-                                     GError **error);

Load the shared library plugin_name - and create a new -NMVpnEditorPlugin instance via the NMVpnEditorPluginFactory -function.

If plugin_name - is not an absolute path name, it assumes the file -is in the plugin directory of NetworkManager. In any case, the call -will do certain checks on the file before passing it to dlopen. -A consequence for that is, that you cannot omit the ".so" suffix -as you could for nm_vpn_editor_plugin_load().

Parameters

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

plugin_name	The path or name of the shared library to load. -The path must either be an absolute filename to an existing file. -Alternatively, it can be the name (without path) of a library in the -plugin directory of NetworkManager.
check_service	if not-null, check that the loaded plugin advertises -the given service.
check_owner	if non-negative, check whether the file is owned -by UID `check_owner` -or by root. In this case also check that -the file is not writable by anybody else.
check_file	optional callback to validate the file prior to -loading the shared library.	[scope call]
user_data	user data for `check_file` -
error	on failure the error reason.

Returns

a new plugin instance or NULL on error.

[transfer full]

Since: 1.2

nm_vpn_editor_plugin_load ()

NMVpnEditorPlugin *
-nm_vpn_editor_plugin_load (const char *plugin_name,
-                           const char *check_service,
-                           GError **error);

Load the shared library plugin_name - and create a new -NMVpnEditorPlugin instance via the NMVpnEditorPluginFactory -function.

This is similar to nm_vpn_editor_plugin_load_from_file(), but -it does no validation of the plugin name, instead passes it directly -to dlopen(). If you have the full path to a plugin file, -nm_vpn_editor_plugin_load_from_file() is preferred.

Parameters

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

plugin_name	The name of the shared library to load. -This path will be directly passed to `dlopen()` without -further checks.
check_service	if not-null, check that the loaded plugin advertises -the given service.
error	on failure the error reason.

Returns

a new plugin instance or NULL on error.

[transfer full]

Since: 1.4

nm_vpn_editor_plugin_get_plugin_info ()

NMVpnPluginInfo *
-nm_vpn_editor_plugin_get_plugin_info (NMVpnEditorPlugin *plugin);

Parameters

----- - - - - - -

plugin

the NMVpnEditorPlugin instance

Returns

if set, return the NMVpnPluginInfo instance.

[transfer none]

Since: 1.4

nm_vpn_editor_plugin_set_plugin_info ()

void
-nm_vpn_editor_plugin_set_plugin_info (NMVpnEditorPlugin *plugin,
-                                      NMVpnPluginInfo *plugin_info);

Set or clear the plugin-info instance. -This takes a weak reference on plugin_info -, to avoid circular -reference as the plugin-info might also reference the editor-plugin.

Parameters

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

plugin	the NMVpnEditorPlugin instance
plugin_info	a NMVpnPluginInfo instance or `NULL`.	[nullable]

Since: 1.4

Types and Values

enum NMVpnEditorPluginCapability

Flags that indicate certain capabilities of the plugin to editor programs.

Members

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

NM_VPN_EDITOR_PLUGIN_CAPABILITY_NONE	- unknown or no capability -
NM_VPN_EDITOR_PLUGIN_CAPABILITY_IMPORT	- the plugin can import new connections -
NM_VPN_EDITOR_PLUGIN_CAPABILITY_EXPORT	- the plugin can export connections -
NM_VPN_EDITOR_PLUGIN_CAPABILITY_IPV6	- the plugin supports IPv6 addressing -

NM_VPN_EDITOR_PLUGIN_NAME

#define NM_VPN_EDITOR_PLUGIN_NAME "name"
-

NM_VPN_EDITOR_PLUGIN_DESCRIPTION

#define NM_VPN_EDITOR_PLUGIN_DESCRIPTION "description"
-

NM_VPN_EDITOR_PLUGIN_SERVICE

#define NM_VPN_EDITOR_PLUGIN_SERVICE "service"
-

NMVpnEditorPluginInterface

typedef struct {
-    GTypeInterface g_iface;
-
-    NMVpnEditor *(*get_editor)(NMVpnEditorPlugin *plugin, NMConnection *connection, GError **error);
-
-    NMVpnEditorPluginCapability (*get_capabilities)(NMVpnEditorPlugin *plugin);
-
-    NMConnection *(*import_from_file)(NMVpnEditorPlugin *plugin, const char *path, GError **error);
-
-    gboolean (*export_to_file)(NMVpnEditorPlugin *plugin,
-                               const char        *path,
-                               NMConnection      *connection,
-                               GError           **error);
-
-    char *(*get_suggested_filename)(NMVpnEditorPlugin *plugin, NMConnection *connection);
-
-    void (*notify_plugin_info_set)(NMVpnEditorPlugin *plugin, NMVpnPluginInfo *plugin_info);
-
-    const NMVpnEditorPluginVT *(*get_vt)(NMVpnEditorPlugin *plugin, gsize *out_vt_size);
-} NMVpnEditorPluginInterface;
-

Interface for VPN editor plugins.

Members

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

`get_editor` ()	returns an NMVpnEditor, pre-filled with values from `connection` -if non-`NULL`.
`get_capabilities` ()	returns a bitmask of capabilities.
`import_from_file` ()	Try to import a connection from the specified path. On -success, return a partial NMConnection object. On error, return `NULL` and -set `error` -with additional information. Note that `error` -can be `NULL`, in -which case no additional error information should be provided.
`export_to_file` ()	Export the given connection to the specified path. Return -`TRUE` on success. On error, return `FALSE` and set `error` -with additional -error information. Note that `error` -can be `NULL`, in which case no -additional error information should be provided.
`get_suggested_filename` ()	For a given connection, return a suggested file -name. Returned value will be `NULL` or a suggested file name to be freed by -the caller.
`notify_plugin_info_set` ()	A callback to be called when the plugin info is set.
`get_vt` ()	return a virtual function table to implement further functions in -the plugin, without requiring to update libnm. Used by `nm_vpn_editor_plugin_get_vt()`.

NMVpnEditor

typedef struct _NMVpnEditor NMVpnEditor;

NMVpnEditorPluginVT

typedef struct _NMVpnEditorPluginVT NMVpnEditorPluginVT;

NMVpnPluginInfo

typedef struct _NMVpnPluginInfo NMVpnPluginInfo;

Property Details

The `“filename”` property

  “filename”                 char *

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”                     char *

The name of the VPN plugin.

Owner: NMVpnPluginInfo

Flags: Read

Default value: NULL

Since: 1.2

The `“description”` property

  “description”              char *

Longer description of the VPN plugin.

Owner: NMVpnEditorPlugin

Flags: Read

Default value: NULL

The `“name”` property

  “name”                     char *

Short display name of the VPN plugin.

Owner: NMVpnEditorPlugin

Flags: Read

Default value: NULL

The `“service”` property

  “service”                  char *

D-Bus service name of the plugin's VPN service.

Owner: NMVpnEditorPlugin

Flags: Read

Default value: NULL

Signal Details

The `“changed”` signal

void
-user_function (NMVpnEditor *nmvpneditor,
-               gpointer     user_data)

Flags: Run First