Using libnm: libnm Reference Manual

+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. +

+ + + + + + + +

1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12

#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));
+}

+ +

+ 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: 1.8.0
+
+  $

+ 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
+2
+3

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"

+ +

+ 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. +

+ + + + + + + +

1
+2
+3
+4
+5
+6

import gi
+gi.require_version('NM', '1.0')
+from gi.repository import NM
+
+client = NM.Client.new(None)
+print ("NetworkManager version " + client.get_version())

+ +

+ 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. +