1 files changed, 35 insertions, 0 deletions
diff --git a/src/settings/plugins/example/README b/src/settings/plugins/example/README
new file mode 100644
index 00000000..224814d1
--- /dev/null
+++ b/src/settings/plugins/example/README
@@ -0,0 +1,35 @@
+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.  It also handles reading and
+  writing the persistent hostname, if the plugin supports hostnames.  Plugins
+  implement the NMSystemConfigInterface interface.  See plugin.c.
+
+2) "connections": subclasses of NMSettingsConnection.  They handle updates to
+  configuration data, deletion, etc.  See NMExampleConnection.c.
+
+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_system_config_factory().  That function creates and returns a singleton
+instance of the plugin's main object, which implements NMSystemConfigInterface.
+That interface is implemented via the object definition in G_DEFINE_TYPE_EXTENDED
+in plugin.c, which registers the interface setup function
+system_config_interface_init(), which when called actually sets up the vtables
+for the functions defined by NMSystemConfigInterface.  Thus there are two
+entry points into the plugin:  nm_system_config_factory() and
+the NMSystemConfigInterface methods.
+
+The plugin also emits various signals (defined by NMSystemConfigInterface)
+which NetworkManager listens for.  These include persistent hostname changes
+(if something modified the file in which the persistent hostname is stored)
+and 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.