libnm: add warning for bindings about broken functions for transferred GPtrArray

In commit 201c153e2599 ('libnm: fix GObject Introspection annotations
for functions returning a GPtrArray') these annotations were changed
to fix Vala bindings. However, bindings may treat the transfer
annotation for GPtrArray differently, so depending on the binding
we either get a leak or a double free.

It's unclear how to fix that. For now, just add a warning to the
documentation to avoid it.

The following reproducer leads to a crash:

    #!/bin/python

    import gi

    gi.require_version("NM", "1.0")
    from gi.repository import NM

    def _pr(msg):
        NM.utils_print(0, msg + "\n")

    def process(nmc):
        for device in nmc.get_devices():
            cons = device.filter_connections(nmc.get_connections())
            _pr(
                "device %s (%s) has %s compatible connections"
                % (device.get_iface(), NM.Object.get_path(device), len(cons))
            )

    process(NM.Client.new())

See-also: https://gitlab.gnome.org/GNOME/gobject-introspection/-/issues/305

2 files changed, 8 insertions, 0 deletions

diff --git a/libnm/nm-access-point.c b/libnm/nm-access-point.c
index bde3ddc17b..25ce44a134 100644
--- a/libnm/nm-access-point.c
+++ b/libnm/nm-access-point.c
@@ -363,6 +363,10 @@ nm_access_point_connection_valid(NMAccessPoint *ap, NMConnection *connection)
  * Returns: (transfer full) (element-type NMConnection): an array of
  * #NMConnections that could be activated with the given @ap.  The array should
  * be freed with g_ptr_array_unref() when it is no longer required.
+ *
+ * WARNING: the transfer annotation for this function may not work correctly
+ *   with bindings. See https://gitlab.gnome.org/GNOME/gobject-introspection/-/issues/305.
+ *   You can filter the list yourself with nm_access_point_connection_valid().
  **/
 GPtrArray *
 nm_access_point_filter_connections(NMAccessPoint *ap, const GPtrArray *connections)
diff --git a/libnm/nm-device.c b/libnm/nm-device.c
index 9e7eb6ba4b..c57f7ce659 100644
--- a/libnm/nm-device.c
+++ b/libnm/nm-device.c
@@ -2814,6 +2814,10 @@ nm_device_connection_compatible(NMDevice *device, NMConnection *connection, GErr
  * Returns: (transfer full) (element-type NMConnection): an array of
  * #NMConnections that could be activated with the given @device.  The array
  * should be freed with g_ptr_array_unref() when it is no longer required.
+ *
+ * WARNING: the transfer annotation for this function may not work correctly
+ *   with bindings. See https://gitlab.gnome.org/GNOME/gobject-introspection/-/issues/305.
+ *   You can filter the list yourself with nm_device_connection_valid().
  **/
 GPtrArray *
 nm_device_filter_connections(NMDevice *device, const GPtrArray *connections)