diff --git a/docs/libnm/libnm-docs.xml b/docs/libnm/libnm-docs.xml
index 705bcfc188..b03efc33f7 100644
--- a/docs/libnm/libnm-docs.xml
+++ b/docs/libnm/libnm-docs.xml
@@ -48,24 +48,130 @@
Overview
-
- libnm maps fairly closely to the actual D-Bus API that NetworkManager
- provides, wrapping the remote D-Bus objects as native GObjects,
- mapping D-Bus signals and properties to GObject signals and properties,
- and providing helpful accessor and utility functions. However, unlike
- the old libnm-util/libnm-glib API, the mapping to the D-Bus API is not
- exact, and various inconveniences and historical anomolies of the D-Bus
- API are papered over.
-
-
- The following is a rough overview of the libnm object structure and
- how to use the various parts of it:
-
-
-
-
-
-
+
+ Introduction to libnm
+
+ libnm is a client library for NetworkManager, the standard Linux network
+ management service. NetworkManager supports a wide variety of network
+ configuration scenarios, hardware devices and protocol families. Most of
+ the functionality is exposed on a
+ D-Bus API,
+ allowing other tools to use the functionality provided by NetworkManager.
+
+
+ libnm provides C language bindings for functionality provided by
+ NetworkManager, optionally useful from other language runtimes as well.
+
+
+ libnm maps fairly closely to the actual D-Bus API that NetworkManager
+ provides, wrapping the remote D-Bus objects as native GObjects,
+ mapping D-Bus signals and properties to GObject signals and properties,
+ and providing helpful accessor and utility functions. However, unlike
+ the old libnm-util/libnm-glib API, the mapping to the D-Bus API is not
+ exact, and various inconveniences and historical anomolies of the D-Bus
+ API are papered over.
+
+
+ The following is a rough overview of the libnm object structure and
+ how to use the various parts of it:
+
+
+
+
+
+
+
+
+
+ Using libnm
+
+ When to use libnm
+
+ libnm is fairly simple to use from C. It's based on glib and GObject.
+ If your project uses these already you'll find integration libnm with your
+ project rather convenient. In fact, the nmcli tool shipped
+ with NetworkManager is based on libnm.
+
+
+ libnm should be also the way to go if your project does something non-trivial
+ with NetworkManager, such as manipulating the connection profiles.
+ That is, if you're writing a specialized networking control tool or a desktop
+ environment, libnm is probably the right choice. The popular desktop
+ environments in fact all use libnm directly or with nm-applet and
+ nm-connection-editor that are all based on libnm.
+
+
+ An alternative to use of libnm is the use of the
+ D-Bus API
+ directly. This gives you larger flexibility and reduces the overhead of linking
+ with the libnm library. This makes sense if your task is simple and you have a good
+ D-Bus library at your disposal. Activating a particular connection profile
+ from a Python script is a good example of a task that is perfectly simple
+ without using libnm.
+
+
+
+
+ How to use libnm
+
+ You can use the libnm's C API directly. To do so, all libnm programs need to
+ include NetworkManager.h that provides necessary definitions.
+ The rest of the API is documented in the reference manual.
+
+
+#include
+
+int
+main (int argc, char *argv[])
+{
+ NMClient *client;
+
+ client = nm_client_new (NULL, NULL);
+ if (client)
+ g_print ("NetworkManager version: %s\n", nm_client_get_version (client));
+}]]>
+
+ Use pkg-config for libnm to discover the necessary
+ compiler flags.
+
+ $ cc $(pkg-config --libs --cflags libnm) -o hello-nm hello-nm.c
+ $ ./hello-nm
+ NetworkManager version: &version;
+ $
+
+ Utilize the PKG_CHECK_MODULES macro to integrate with an
+ autoconf-based build system. It's also recommended to use
+ NM_VERSION_MIN_REQUIRED and NM_VERSION_MAX_ALLOWED
+ macros to tell libnm headers which API version does your application need to work with.
+ If you use them, the compiler will warn you when you use functionality that is not
+ available in the versions you specified.
+
+ = 1.8)
+LIBNM_CFLAGS="$LIBNM_CFLAGS -DNM_VERSION_MIN_REQUIRED=NM_VERSION_1_8"
+LIBNM_CFLAGS="$LIBNM_CFLAGS -DNM_VERSION_MAX_ALLOWED=NM_VERSION_1_8"]]>
+
+ You can use libnm from other languages than C with the use of GObject introspection.
+ This includes Perl, Python, Javascript, Lua, Ruby and more. The example below shows what the
+ typical libnm use in Python would look like.
+
+
+
+ There's NM-1.0 Python API Reference
+ maintained a third party that is generated from the introspection metadata.
+
+
+ In general, the C API documentation applies to the use GObject introspection
+ from other languages, with the calling convention respecting the language's
+ customs. Consult the source tree for
+ some examples.
+
+
+