diff options
| -rw-r--r-- | docs/libnm/libnm-docs.xml | 142 |
1 files changed, 124 insertions, 18 deletions
diff --git a/docs/libnm/libnm-docs.xml b/docs/libnm/libnm-docs.xml index 705bcfc18..b03efc33f 100644 --- a/docs/libnm/libnm-docs.xml +++ b/docs/libnm/libnm-docs.xml @@ -48,24 +48,130 @@ <chapter id="ref-overview"> <title>Overview</title> - <para> - 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. - </para> - <para> - The following is a rough overview of the libnm object structure and - how to use the various parts of it: - <mediaobject id="libnm-overview"> - <imageobject> - <imagedata fileref="libnm.png" format="PNG"/> - </imageobject> - </mediaobject> - </para> + <section id="intro"> + <title>Introduction to libnm</title> + <para> + 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 + <ulink url="https://developer.gnome.org/NetworkManager/stable/spec.html">D-Bus API</ulink>, + allowing other tools to use the functionality provided by NetworkManager. + </para> + <para> + libnm provides C language bindings for functionality provided by + NetworkManager, optionally useful from other language runtimes as well. + </para> + <para> + 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. + </para> + <para> + The following is a rough overview of the libnm object structure and + how to use the various parts of it: + <mediaobject id="libnm-overview"> + <imageobject> + <imagedata fileref="libnm.png" format="PNG"/> + </imageobject> + </mediaobject> + </para> + </section> + + <section id="usage"> + <title>Using libnm</title> + <simplesect> + <title>When to use libnm</title> + <para> + 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 <command>nmcli</command> tool shipped + with NetworkManager is based on libnm. + </para> + <para> + 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. + </para> + <para> + An alternative to use of libnm is the use of the + <ulink url="https://developer.gnome.org/NetworkManager/stable/spec.html">D-Bus API</ulink> + 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. + </para> + </simplesect> + + <simplesect> + <title>How to use libnm</title> + <para> + You can use the libnm's C API directly. To do so, all libnm programs need to + include <filename>NetworkManager.h</filename> that provides necessary definitions. + The rest of the API is documented in the reference manual. + </para> + <informalexample><programlisting><![CDATA[#include <glib.h> +#include <NetworkManager.h> + +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)); +}]]></programlisting></informalexample> + <para> + Use <command>pkg-config</command> for <varname>libnm</varname> to discover the necessary + compiler flags. + </para> + <screen><prompt>$ </prompt><userinput>cc $(pkg-config --libs --cflags libnm) -o hello-nm hello-nm.c</userinput> + <prompt>$ </prompt><userinput>./hello-nm</userinput> + NetworkManager version: &version; + <prompt>$ </prompt></screen> + <para> + Utilize the <varname>PKG_CHECK_MODULES</varname> macro to integrate with an + autoconf-based build system. It's also recommended to use + <varname>NM_VERSION_MIN_REQUIRED</varname> and <varname>NM_VERSION_MAX_ALLOWED</varname> + 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. + </para> + <informalexample><programlisting><![CDATA[PKG_CHECK_MODULES(LIBNM, libnm >= 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"]]></programlisting></informalexample> + <para> + 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. + </para> + <informalexample><programlisting><![CDATA[import gi +gi.require_version('NM', '1.0') +from gi.repository import NM + +client = NM.Client.new(None) +print ("NetworkManager version " + client.get_version())]]></programlisting></informalexample> + <para> + There's <ulink url="https://lazka.github.io/pgi-docs/#NM-1.0">NM-1.0 Python API Reference</ulink> + maintained a third party that is generated from the introspection metadata. + </para> + <para> + 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 + <ulink url="https://cgit.freedesktop.org/NetworkManager/NetworkManager/tree/examples">some examples</ulink>. + </para> + </simplesect> + </section> </chapter> <chapter> |