Imported Upstream version 1.1.90 upstream/1.1.90

1 files changed, 33 insertions, 0 deletions

diff --git a/src/settings/plugins/README b/src/settings/plugins/README
new file mode 100644
index 00000000..307d0bb1
--- /dev/null
+++ b/src/settings/plugins/README
@@ -0,0 +1,33 @@
+Plugins generally have three components:
+
+1) plugin object: manages the individual "connections", which are
+  just objects wrapped around on-disk config data.  The plugin handles requests
+  to add new connections via the NM D-Bus API, and also watches config
+  directories for changes to configuration data.  Plugins implement the
+  NMSettingsPlugin interface.  See plugin.c.
+
+2) "connections": subclasses of NMSettingsConnection.  They handle updates to
+  configuration data, deletion, etc.  See NMKeyfileConnection.
+
+3) reader/writer code: typically a separate static library that gets linked
+  into the main plugin shared object, so they can be unit tested separately
+  from the plugin.  This code should read config data from disk and create
+  an NMConnection from it, and be capable of taking an NMConnection and writing
+  out appropriate configuration data to disk.
+
+NM will first call the "factory" function that every module must provide, which
+is nm_settings_plugin_factory().  That function creates and returns a singleton
+instance of the plugin's main object, which implements NMSettingsPlugin.
+That interface is implemented via the object definition in G_DEFINE_TYPE_EXTENDED
+in plugin.c, which registers the interface setup function
+settings_plugin_interface_init(), which when called actually sets up the vtables
+for the functions defined by NMSettingsPluginInterface.  Thus there are two
+entry points into the plugin:  nm_settings_plugin_factory() and
+the NMSettingsPluginInterface methods.
+
+The plugin also emits various signals (defined by NMSettingsPluginInterface)
+which NetworkManager listens for.  These include notifications of new
+connections if they were created via changes to the on-disk files.  The
+"connection" objects can also emit signals (defined by the NMSettingsConnection
+and NMConnection superclasses) when the connections' backing storage gets
+changed or deleted.