These setters not only invoke a synchronous D-Bus call (ignoring the
return value). They also modify the content of the cache client-side,
bypassing the information that we receive via notifications from the
server.
Also, they don't emit property changed signals, but in any case they
are broken beyond repair.
Fully mark them as deprecated. Note that they were already marked as
_NM_DEPRECATED_SYNC_METHOD. However, that does not actually mark
the API as deprecated, because fully deprecating all synchronous
methods is premature at this point.
These types are all subclasses of NMObject. These instances are commonly
created by NMClient itself. It makes no sense that a user would
instantiate the type. Much less does it make sense to subclass them.
Hide the object and class structures from public API.
This is an API and ABI break, but of something that is very likely
unused.
This is mainly done to embed the private structure in the object itself.
This has benefits for performance and debugability. But most
importantly, we can obtain a static offset where to access the private data.
That means, we can use the information to access the data pointer
generically, as we will need later.
This is not done for the internal types NMManager, NMRemoteSettings,
and NMDnsManager. These types will be dropped later.
Note that D-Bus is fundamentally asynchronous. Doing blocking calls
on top of D-Bus is odd, especially for libnm's NMClient. That is because
NMClient essentially is a client-side cache of the objects from the D-Bus
interface. This cache should be filled exclusively by (asynchronous) D-Bus
events (PropertiesChanged). So, making a blocking D-Bus call means to wait
for a response and return it, while queuing all messages that are received
in the meantime.
Basically there are three ways how a synchronous API on NMClient could behave:
1) the call just calls g_dbus_connection_call_sync(). This means
that libnm sends a D-Bus request via GDBusConnection, and blockingly
waits for the response. All D-Bus messages that get received in the
meantime are queued in the GMainContext that belongs to NMClient.
That means, none of these D-Bus events are processed until we
iterate the GMainContext after the call returns. The effect is,
that NMClient (and all cached objects in there) are unaffected by
the D-Bus request.
Most of the synchronous API calls in libnm are of this kind.
The problem is that the strict ordering of D-Bus events gets
violated.
For some API this is not an immediate problem. Take for example
nm_device_wifi_request_scan(). The call merely blockingly tells
NetworkManager to start scanning, but since NetworkManager's D-Bus
API does not directly expose any state that tells whether we are
currently scanning, this out of order processing of the D-Bus
request is a small issue.
The problem is more obvious for nm_client_networking_set_enabled().
After calling it, NM_CLIENT_NETWORKING_ENABLED is still unaffected
and unchanged, because the PropertiesChanged signal from D-Bus
is not yet processed.
This means, while you make such a blocking call, NMClient's state
does not change. But usually you perform the synchronous call
to change some state. In this form, the blocking call is not useful,
because NMClient only changes the state after iterating the GMainContext,
and not after the blocking call returns.
2) like 1), but after making the blocking g_dbus_connection_call_sync(),
update the NMClient cache artificially. This is what
nm_manager_check_connectivity() does, to "fix" bgo#784629.
This also has the problem of out-of-order events, but it kinda
solves the problem of not changing the state during the blocking
call. But it does so by hacking the state of the cache. I think
this is really wrong because the state should only be updated from
the ordered stream of D-Bus messages (PropertiesChanged signal and
similar). When libnm decides to modify the state, there may be already
D-Bus messages queued that affect this very state.
3) instead of calling g_dbus_connection_call_sync(), use the
asynchronous g_dbus_connection_call(). If we would use a sepaate
GMainContext for all D-Bus related calls, we could ensure that
while we block for the response, we iterate that internal main context.
This might be nice, because all events are processed in order and
after the blocking call returns, the NMClient state is up to date.
The are problems however: current blocking API does not do this,
so it's a significant change in behavior. Also, it might be
unexpected to the user that during the blocking call the entire
content of NMClient's cache might change and all pointers to the
cache might be invalidated. Also, of course NMClient would invoke
signals for all the changes that happen.
Another problem is that this would be more effort to implement
and it involves a small performance overhead for all D-Bus related
calls (because we have to serialize all events in an internal
GMainContext first and then invoke them on the caller's context).
Also, if the users wants this behavior, they could implement it themself
by running libnm in their own GMainContext. Note that libnm might
have bugs to make that really working, but that should be fixed
instead of adding such synchrnous API behavior.
Read also [1], for why blocking calls are wrong.
[1] https://smcv.pseudorandom.co.uk/2008/11/nonblocking/
So, all possible behaviors for synchronous API have severe behavioural
issues. Mark all this API as deprecated. Also, this serves the purpose of
identifying blocking D-Bus calls in libnm.
Note that "deprecated" here does not really mean that the API is going
to be removed. We don't break API. The user may:
- continue to use this API. It's deprecated, awkward and discouraged,
but if it works, by all means use it.
- use asynchronous API. That's the only sensible way to use D-Bus.
If libnm lacks a certain asynchronous counterpart, it should be
added.
- use GDBusConnection directly. There really isn't anything wrong
with D-Bus or GDBusConnection. This deprecated API is just a wrapper
around g_dbus_connection_call_sync(). You may call it directly
without feeling dirty.
---
The only other remainging API is the synchronous GInitable call for
NMClient. That is an entirely separate beast and not particularly
wrong (from an API point of view).
Note that synchronous API in NMSecretAgentOld, NMVpnPluginOld and
NMVpnServicePlugin as not deprecated here. These types are not part
of the D-Bus cache and while they have similar issues, it's less severe
because they have less state.
We no longer add these. If you use Emacs, configure it yourself.
Also, due to our "smart-tab" usage the editor anyway does a subpar
job handling our tabs. However, on the upside every user can choose
whatever tab-width he/she prefers. If "smart-tabs" are used properly
(like we do), every tab-width will work.
No manual changes, just ran commands:
F=($(git grep -l -e '-\*-'))
sed '1 { /\/\* *-\*- *[mM]ode.*\*\/$/d }' -i "${F[@]}"
sed '1,4 { /^\(#\|--\|dnl\) *-\*- [mM]ode/d }' -i "${F[@]}"
Check remaining lines with:
git grep -e '-\*-'
The ultimate purpose of this is to cleanup our files and eventually use
SPDX license identifiers. For that, first get rid of the boilerplate lines.
Add the const qualifier to the attribute name in LLDP API functions so
that const strings and string literals are accepted. This change is
backwards compatible for existing users of the API.
In practice, this should only matter when there are multiple
header files with the same name. That is something we try
to avoid already, by giving headers a distinct name.
When building NetworkManager itself, we clearly want to use
double-quotes for including our own headers.
But we also want to do that in our public headers. For example:
./a.c
#include <stdio.h>
#include <nm-1.h>
void main() {
printf ("INCLUDED %s/nm-2.h\n", SYMB);
}
./1/nm-1.h
#include <nm-2.h>
./1/nm-2.h
#define SYMB "1"
./2/nm-2.h
#define SYMB "2"
$ cc -I./2 -I./1 ./a.c
$ ./a.out
INCLUDED 2/nm-2.h
Exceptions to this are
- headers in "shared/nm-utils" that include <NetworkManager.h>. These
headers are copied into projects and hence used like headers owned by
those projects.
- examples/C
This is required to add objects in the "Types and Values" section and
in the API index. Later, we may want to add useful content in those
empty comments.
This breaks API and ABI for the functions related to Reapply,
which got introduced in the current 1.1 development phase.
The version-id is here to allow users to error out if the connection
on the device was changed by a concurrent action.
https://bugzilla.gnome.org/show_bug.cgi?id=761714
GLib introspection requires all types returned by public functions to
be GObjects, basic types or boxed types in order to correctly manage
resources. NMLldpNeighbor was a plain struct and GI complained with:
Warning: NM: nm_lldp_neighbor_new: return value: Invalid non-constant return of bare structure or union; register as boxed type or (skip)
To fix this define NMLldpNeighbor as a boxed type.
Fixes: d3d2b49400
Create NMIPConfig as the parent of NMIP4Config and NMIP6Config, and
remove the two subclasses from the public API; while it's convenient
to still have both internally, they are now identical to the outside
world.
libnm mostly used GPtrArrays in its APIs, except that arrays of
connections were usually GSLists. Fix this and make them GPtrArrays
too (and rename nm_client_list_connections() to
nm_client_get_connections() to match everything else).
Merge libnm's NMDeviceError and the daemon's NMDeviceError into a
single enum (in nm-errors.h). Register the domain with D-Bus, and add
a test that the client side decodes it correctly.
The daemon's NM_DEVICE_ERROR_CONNECTION_INVALID gets absorbed into
libnm's NM_DEVICE_ERROR_INVALID_CONNECTION, and
NM_DEVICE_ERROR_UNSUPPORTED_DEVICE_TYPE gets dropped, since it was
only returned from one place, which is now using
NM_DEVICE_ERROR_FAILED, since (a) it ought to be a "can't happen", and
(b) the only caller of that function just logs error->message and then
frees the error without ever looking at the code.
As with the settings, each device type was defining its own error
type, containing either redundant or non-useful error codes. Drop all
of the subtype-specific errors, and reduce things to just
NM_DEVICE_ERROR_FAILED, NM_DEVICE_ERROR_INCOMPATIBLE_CONNECTION, and
NM_DEVICE_ERROR_INVALID_CONNECTION.
The device-type-specific errors were only returned from their
nm_device_connection_compatible() implementations, so this is also a
good opportunity to simplify those, by moving duplicated functionality
into the base NMDevice implementation, and then allowing the
subclasses to assume that the connection has already been validated in
their own code. Most of the implementations now just check that the
connection has the correct type for the device (which can't be done at
the NMDevice level since some device types (eg, Ethernet) support
multiple connection types.)
Also, make sure that all of the error messages are localized.
Add the missing variant in most places in the API where previously
there was either only a synchronous version or only an asynchronous
version.
There is not yet a synchronous nm_client_activate_connection(),
nm_client_add_and_activate_connection(), or
nm_remote_settings_add_connection(), because the existing async code
depends on waiting for other asynchronous events, so making them run
synchronously is slightly more complicated. But these APIs can be
added later.
Make synchronous APIs take GCancellables, and make asynchronous APIs
use GAsyncReadyCallbacks and have names ending in "_async", with
"_finish" functions to retrieve the results.
Also, make nm_client_activate_connection_finish(),
nm_client_add_and_activate_finish(), and
nm_remote_settings_add_connection_finish() be (transfer full) rather
than (transfer none), because the refcounting semantics become
slightly confusing in some edge cases otherwise.
The NMDevice:state-reason property was awkward to work with since it
was a tuple of two values (state and reason), and likewise, although
we had nm_device_get_state() to return just the state, there was no
corresponding function to get just the reason.
Fix this; make the state-reason property contain just the
NMDeviceStateReason, and make nm_device_get_state_reason() return just
that.
Previously, src/nm-ip4-config.h, libnm/nm-ip4-config.h, and
libnm-glib/nm-ip4-config.h all used "NM_IP4_CONFIG_H" as an include
guard, which meant that nm-test-utils.h could not tell which of them
was being included (and so, eg, if you tried to include
nm-ip4-config.h in a libnm test, it would fail to compile because
nm-test-utils.h was referring to symbols in src/nm-ip4-config.h).
Fix this by changing the include guards in the non-API-stable parts of
the tree:
- libnm-glib/nm-ip4-config.h remains NM_IP4_CONFIG_H
- libnm/nm-ip4-config.h now uses __NM_IP4_CONFIG_H__
- src/nm-ip4-config.h now uses __NETWORKMANAGER_IP4_CONFIG_H__
And likewise for all other headers.
The two non-"nm"-prefixed headers, libnm/NetworkManager.h and
src/NetworkManagerUtils.h are now __NETWORKMANAGER_H__ and
__NETWORKMANAGER_UTILS_H__ respectively, which, while not entirely
consistent with the general scheme, do still mostly make sense in
isolation.
Add NetworkManager.h, which includes all of the other NM header, and
require all external users of libnm to use that rather than the
individual headers.
(An exception is made for nm-dbus-interface.h,
nm-vpn-dbus-interface.h, and nm-version.h, which can be included
separately.)
"NetworkManager.h"'s name (and non-standard capitalization) suggest
that it's some sort of high-level super-important header, but it's
really just low-level D-Bus stuff. Rename it to "nm-dbus-interface.h"
and likewise "NetworkManagerVPN.h" to "nm-vpn-dbus-interface.h"
Add reserved slots to those classes that were missing them (or had run
out), and sync up the number of slots across classes:
- 8 slots for "important" classes, abstract base classes, and
classes we expect we might need to add new virtual methods or
signals to later.
- 4 for everything else
Also, rearrange the class elements in a few places into standard order
(signals first, then methods).
GLib/Gtk have mostly settled on the convention that two-letter
acronyms in type names remain all-caps (eg, "IO"), but longer acronyms
become initial-caps-only (eg, "Tcp").
NM was inconsistent, with most long acronyms using initial caps only
(Adsl, Cdma, Dcb, Gsm, Olpc, Vlan), but others using all caps (DHCP,
PPP, PPPOE, VPN). Fix libnm and src/ to use initial-caps only for all
three-or-more-letter-long acronyms (and update nmcli and nmtui for the
libnm changes).
Remove deprecated functions and enum types.
For now, deprecated properties are still around, because removing them
would cause warnings when talking to older implementations.
This commit begins creating the new "libnm", which will replace
libnm-util and libnm-glib.
The main reason for the libnm-util/libnm-glib split is that the daemon
needs to link to libnm-util (to get NMSettings, NMConnection, etc),
but can't link to libnm-glib (because it uses many of the same type
names as the NetworkManager daemon. eg, NMDevice). So the daemon links
to only libnm-util, but basically all clients link to both.
With libnm, there will be only a single client-visible library, and
NetworkManager will internally link against a private "libnm-core"
containing the parts that used to be in libnm-util.
(The "libnm-core" parts still need to be in their own directory so
that the daemon can see those header files without also seeing the
ones in libnm/ that conflict with its own headers.)
[This commit just copies the source code from libnm-util/ to
libnm-core/, and libnm-glib/ to libnm/:
mkdir -p libnm-core/tests/
mkdir -p libnm/tests/
cp libnm-util/*.[ch] libnm-util/nm-version.h.in libnm-core/
rm -f libnm-core/nm-version.h libnm-core/nm-setting-template.[ch] libnm-core/nm-utils-enum-types.[ch]
cp libnm-util/tests/*.[ch] libnm-core/tests/
cp libnm-glib/*.[ch] libnm/
rm -f libnm/libnm_glib.[ch] libnm/libnm-glib-test.c libnm/nm-glib-enum-types.[ch]
cp libnm-glib/tests/*.[ch] libnm/tests/
]
