This allows implementing some convenience features in nmcli -- listing
the backing store for the connection in "nmcli c show", and using the
filename for specifying connection in "nmcli c up/down".
Eventually, paired with ReloadConnections(), this could be used to
implement something similar to what "systemctl edit" does for units
(though we'd need to pick another command name as we aready use
"nmcli c edit" for something different).
The D-Bus interface already has a boolean property "Unsaved".
While that is nicer too look at (in the API), adding a new flag
is very cumbersome, and also has more overhead. For example,
it requires extending the D-Bus API, all the way down to libnm.
Add a flags argument, that will allow to add future boolean
flags easier.
Extend the Update2 flags to allow marking a connection as volatile.
Making a connection as volatile means that the connection stays alive
as long as an active connection references it.
It is correct that Update2() returns before the connection is actually
deleted. It might take an arbitrary long time until the volatile
mechanism cleans up the connection.
Also add two more IN_MEMORY flags: "detached" and "only".
The existing NM_SETTINGS_UPDATE2_FLAG_IN_MEMORY would not detach nor
delete the possible file on disk. That is, the mode only changes what NM
thinks is the current content of the connection profile. It would not delete
the file on disk nor would it detach the profile in-memory from the file.
As such, later persisting the connection again to disk would overwrite
the file, and deleting the profile, would delete the file.
Now add two new IN_MEMORY modes.
NM_SETTINGS_UPDATE2_FLAG_IN_MEMORY_DETACH is like making the connection
in-memory only, but forgetting that there might be any profile on disk.
That means, a later Delete() would not delete the file. Similarly, a
later Update2() that persists the connection again, would not overwrite
the existing file on disk, instead it would choose a new file name.
On the other hand, NM_SETTINGS_UPDATE2_FLAG_IN_MEMORY_ONLY would delete
a potential file from disk right away.
It's clear that "volatile" only makes sense with either "in-memory-detached"
or "in-memory-only". That is, the file on disk should be deleted right away
(before the in-memory part is garbage collected) or the file on disk should
be forgotten.
We already have Update(), UpdateUnsaved() and Save(), which serve
similar purposes. We will need a form of update with another argument.
Most notably, to block autoconnect while doing the update.
Other use cases could be to prevent reapplying connection.zone and
connection.metered, to to reapply all changes.
Instead of adding a specific update function that only serves that
new use-case, add a extensible Update2() function. It can be extended
to cope with future variants of update.
This makes it easier to install the files with proper names.
Also, it makes the makefile rules slightly simpler.
Lastly, the documentation is now generated into docs/api, which makes it
possible to get rid of the awkward relative file names in docbook.
