webrtc: remove private properties/signals from the now public ice object

We don't want to expose all of the webrtcbin internals to the world.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gst-plugins-bad/-/merge_requests/1444>

docs/plugins/gst_plugins_cache.json

@@ -223944,7 +223944,7 @@
                 "kind": "object",
                 "properties": {
                     "agent": {
-                        "blurb": "ICE agent in use by this object",
+                        "blurb": "ICE agent in use by this object. WARNING! Accessing this property may have disastrous consequences for the operation of webrtcbin. Other ICE implementations may not have the same interface.",
                         "conditionally-available": false,
                         "construct": false,
                         "construct-only": false,
@@ -223954,30 +223954,6 @@
                         "type": "NiceAgent",
                         "writable": false
                     },
-                    "controller": {
-                        "blurb": "Whether the ICE agent is the controller or controlled. In WebRTC, the initial offerrer is the ICE controller.",
-                        "conditionally-available": false,
-                        "construct": false,
-                        "construct-only": false,
-                        "controllable": false,
-                        "default": "true",
-                        "mutable": "null",
-                        "readable": true,
-                        "type": "gboolean",
-                        "writable": true
-                    },
-                    "force-relay": {
-                        "blurb": "Force all traffic to go through a relay.",
-                        "conditionally-available": false,
-                        "construct": false,
-                        "construct-only": false,
-                        "controllable": false,
-                        "default": "false",
-                        "mutable": "null",
-                        "readable": true,
-                        "type": "gboolean",
-                        "writable": true
-                    },
                     "ice-tcp": {
                         "blurb": "Whether the agent should use ICE-TCP when gathering candidates",
                         "conditionally-available": false,
@@ -224001,30 +223977,6 @@
                         "readable": true,
                         "type": "gboolean",
                         "writable": true
-                    },
-                    "stun-server": {
-                        "blurb": "The STUN server of the form stun://hostname:port",
-                        "conditionally-available": false,
-                        "construct": false,
-                        "construct-only": false,
-                        "controllable": false,
-                        "default": "NULL",
-                        "mutable": "null",
-                        "readable": true,
-                        "type": "gchararray",
-                        "writable": true
-                    },
-                    "turn-server": {
-                        "blurb": "The TURN server of the form turn(s)://username:password@host:port",
-                        "conditionally-available": false,
-                        "construct": false,
-                        "construct-only": false,
-                        "controllable": false,
-                        "default": "NULL",
-                        "mutable": "null",
-                        "readable": true,
-                        "type": "gchararray",
-                        "writable": true
                     }
                 },
                 "signals": {
@@ -224038,20 +223990,6 @@
                         ],
                         "return-type": "gboolean",
                         "when": "last"
-                    },
-                    "on-ice-candidate": {
-                        "args": [
-                            {
-                                "name": "arg0",
-                                "type": "guint"
-                            },
-                            {
-                                "name": "arg1",
-                                "type": "gchararray"
-                            }
-                        ],
-                        "return-type": "void",
-                        "when": "last"
                     }
                 }
             }

ext/webrtc/gstwebrtcbin.c

@@ -3270,7 +3270,7 @@ _create_answer_task (GstWebRTCBin * webrtc, const GstStructure * options)
   /* FIXME: can we add not matched transceivers? */
 
   /* XXX: only true for the initial offerer */
-  g_object_set (webrtc->priv->ice, "controller", FALSE, NULL);
+  gst_webrtc_ice_set_is_controller (webrtc->priv->ice, FALSE);
 
 out:
   g_strfreev (bundled);
@@ -4463,7 +4463,7 @@ _set_description_task (GstWebRTCBin * webrtc, struct set_description *sd)
 
     /* get the current value so we don't change ice controller from TRUE to
      * FALSE on renegotiation or once set to TRUE for the initial local offer */
-    g_object_get (webrtc->priv->ice, "controller", &ice_controller, NULL);
+    ice_controller = gst_webrtc_ice_get_is_controller (webrtc->priv->ice);
 
     /* we control ice negotiation if we send the initial offer */
     ice_controller |=
@@ -4477,7 +4477,7 @@ _set_description_task (GstWebRTCBin * webrtc, struct set_description *sd)
 
     GST_DEBUG_OBJECT (webrtc, "we are in ice controlling mode: %s",
         ice_controller ? "true" : "false");
-    g_object_set (webrtc->priv->ice, "controller", ice_controller, NULL);
+    gst_webrtc_ice_set_is_controller (webrtc->priv->ice, ice_controller);
   }
 
   if (new_signaling_state == GST_WEBRTC_SIGNALING_STATE_STABLE) {
@@ -5880,8 +5880,12 @@ gst_webrtc_bin_set_property (GObject * object, guint prop_id,
 
   switch (prop_id) {
     case PROP_STUN_SERVER:
+      gst_webrtc_ice_set_stun_server (webrtc->priv->ice,
+          g_value_get_string (value));
+      break;
     case PROP_TURN_SERVER:
-      g_object_set_property (G_OBJECT (webrtc->priv->ice), pspec->name, value);
+      gst_webrtc_ice_set_turn_server (webrtc->priv->ice,
+          g_value_get_string (value));
       break;
     case PROP_BUNDLE_POLICY:
       if (g_value_get_enum (value) == GST_WEBRTC_BUNDLE_POLICY_BALANCED) {
@@ -5892,9 +5896,9 @@ gst_webrtc_bin_set_property (GObject * object, guint prop_id,
       break;
     case PROP_ICE_TRANSPORT_POLICY:
       webrtc->ice_transport_policy = g_value_get_enum (value);
-      g_object_set (webrtc->priv->ice, "force-relay",
+      gst_webrtc_ice_set_force_relay (webrtc->priv->ice,
           webrtc->ice_transport_policy ==
-          GST_WEBRTC_ICE_TRANSPORT_POLICY_RELAY ? TRUE : FALSE, NULL);
+          GST_WEBRTC_ICE_TRANSPORT_POLICY_RELAY ? TRUE : FALSE);
       break;
     case PROP_LATENCY:
       g_object_set_property (G_OBJECT (webrtc->rtpbin), "latency", value);
@@ -5956,8 +5960,12 @@ gst_webrtc_bin_get_property (GObject * object, guint prop_id,
       g_value_set_boxed (value, webrtc->pending_remote_description);
       break;
     case PROP_STUN_SERVER:
+      g_value_take_string (value,
+          gst_webrtc_ice_get_stun_server (webrtc->priv->ice));
+      break;
     case PROP_TURN_SERVER:
-      g_object_get_property (G_OBJECT (webrtc->priv->ice), pspec->name, value);
+      g_value_take_string (value,
+          gst_webrtc_ice_get_turn_server (webrtc->priv->ice));
       break;
     case PROP_BUNDLE_POLICY:
       g_value_set_enum (value, webrtc->bundle_policy);
@@ -5986,8 +5994,9 @@ gst_webrtc_bin_constructed (GObject * object)
 
   name = g_strdup_printf ("%s:ice", GST_OBJECT_NAME (webrtc));
   webrtc->priv->ice = gst_webrtc_ice_new (name);
-  g_signal_connect (webrtc->priv->ice, "on-ice-candidate",
+
-      G_CALLBACK (_on_local_ice_candidate_cb), webrtc);
+  gst_webrtc_ice_set_on_ice_candidate (webrtc->priv->ice,
+      (GstWebRTCIceOnCandidateFunc) _on_local_ice_candidate_cb, webrtc, NULL);
 
   g_free (name);
 }

ext/webrtc/gstwebrtcice.c

@@ -46,8 +46,6 @@ gst_webrtc_ice_error_quark (void)
 enum
 {
   SIGNAL_0,
-  ON_ICE_CANDIDATE_SIGNAL,
-  ON_ICE_GATHERING_STATE_CHANGE_SIGNAL,
   ADD_LOCAL_IP_ADDRESS_SIGNAL,
   LAST_SIGNAL,
 };
@@ -55,12 +53,7 @@ enum
 enum
 {
   PROP_0,
-  PROP_ICE_GATHERING_STATE,
-  PROP_STUN_SERVER,
-  PROP_TURN_SERVER,
-  PROP_CONTROLLER,
   PROP_AGENT,
-  PROP_FORCE_RELAY,
   PROP_ICE_TCP,
   PROP_ICE_UDP,
 };
@@ -78,6 +71,10 @@ struct _GstWebRTCICEPrivate
   GMainLoop *loop;
   GMutex lock;
   GCond cond;
+
+  GstWebRTCIceOnCandidateFunc on_candidate;
+  gpointer on_candidate_data;
+  GDestroyNotify on_candidate_notify;
 };
 
 #define gst_webrtc_ice_parent_class parent_class
@@ -515,8 +512,11 @@ _on_new_candidate (NiceAgent * agent, NiceCandidate * candidate,
   }
 
   attr = nice_agent_generate_local_candidate_sdp (agent, candidate);
-  g_signal_emit (ice, gst_webrtc_ice_signals[ON_ICE_CANDIDATE_SIGNAL],
+
-      0, item->session_id, attr);
+  if (ice->priv->on_candidate)
+    ice->priv->on_candidate (ice, item->session_id, attr,
+        ice->priv->on_candidate_data);
+
   g_free (attr);
 }
 
@@ -728,6 +728,42 @@ gst_webrtc_ice_gather_candidates (GstWebRTCICE * ice,
   return gst_webrtc_ice_stream_gather_candidates (stream);
 }
 
+void
+gst_webrtc_ice_set_is_controller (GstWebRTCICE * ice, gboolean controller)
+{
+  g_object_set (G_OBJECT (ice->priv->nice_agent), "controlling-mode",
+      controller, NULL);
+}
+
+gboolean
+gst_webrtc_ice_get_is_controller (GstWebRTCICE * ice)
+{
+  gboolean ret;
+  g_object_get (G_OBJECT (ice->priv->nice_agent), "controlling-mode",
+      &ret, NULL);
+  return ret;
+}
+
+void
+gst_webrtc_ice_set_force_relay (GstWebRTCICE * ice, gboolean force_relay)
+{
+  g_object_set (G_OBJECT (ice->priv->nice_agent), "force-relay", force_relay,
+      NULL);
+}
+
+void
+gst_webrtc_ice_set_on_ice_candidate (GstWebRTCICE * ice,
+    GstWebRTCIceOnCandidateFunc func, gpointer user_data, GDestroyNotify notify)
+{
+  if (ice->priv->on_candidate_notify)
+    ice->priv->on_candidate_notify (ice->priv->on_candidate_data);
+  ice->priv->on_candidate = NULL;
+
+  ice->priv->on_candidate = func;
+  ice->priv->on_candidate_data = user_data;
+  ice->priv->on_candidate_notify = notify;
+}
+
 static void
 _clear_ice_stream (struct NiceStreamItem *item)
 {
@@ -816,6 +852,54 @@ out:
   return uri;
 }
 
+void
+gst_webrtc_ice_set_stun_server (GstWebRTCICE * ice, const gchar * uri_s)
+{
+  GstUri *uri = gst_uri_from_string (uri_s);
+  const gchar *msg = "must be of the form stun://<host>:<port>";
+
+  GST_DEBUG_OBJECT (ice, "setting stun server, %s", uri_s);
+
+  if (!uri) {
+    GST_ERROR_OBJECT (ice, "Couldn't parse stun server '%s', %s", uri_s, msg);
+    return;
+  }
+
+  if (ice->stun_server)
+    gst_uri_unref (ice->stun_server);
+  ice->stun_server = uri;
+}
+
+gchar *
+gst_webrtc_ice_get_stun_server (GstWebRTCICE * ice)
+{
+  if (ice->stun_server)
+    return gst_uri_to_string (ice->stun_server);
+  else
+    return NULL;
+}
+
+void
+gst_webrtc_ice_set_turn_server (GstWebRTCICE * ice, const gchar * uri_s)
+{
+  GstUri *uri = _validate_turn_server (ice, uri_s);
+
+  if (uri) {
+    if (ice->turn_server)
+      gst_uri_unref (ice->turn_server);
+    ice->turn_server = uri;
+  }
+}
+
+gchar *
+gst_webrtc_ice_get_turn_server (GstWebRTCICE * ice)
+{
+  if (ice->turn_server)
+    return gst_uri_to_string (ice->turn_server);
+  else
+    return NULL;
+}
+
 static void
 gst_webrtc_ice_set_property (GObject * object, guint prop_id,
     const GValue * value, GParamSpec * pspec)
@@ -823,41 +907,6 @@ gst_webrtc_ice_set_property (GObject * object, guint prop_id,
   GstWebRTCICE *ice = GST_WEBRTC_ICE (object);
 
   switch (prop_id) {
-    case PROP_STUN_SERVER:{
-      const gchar *s = g_value_get_string (value);
-      GstUri *uri = gst_uri_from_string (s);
-      const gchar *msg = "must be of the form stun://<host>:<port>";
-
-      GST_DEBUG_OBJECT (ice, "setting stun server, %s", s);
-
-      if (!uri) {
-        GST_ERROR_OBJECT (ice, "Couldn't parse stun server '%s', %s", s, msg);
-        return;
-      }
-
-      if (ice->stun_server)
-        gst_uri_unref (ice->stun_server);
-      ice->stun_server = uri;
-      break;
-    }
-    case PROP_TURN_SERVER:{
-      GstUri *uri = _validate_turn_server (ice, g_value_get_string (value));
-
-      if (uri) {
-        if (ice->turn_server)
-          gst_uri_unref (ice->turn_server);
-        ice->turn_server = uri;
-      }
-      break;
-    }
-    case PROP_CONTROLLER:
-      g_object_set_property (G_OBJECT (ice->priv->nice_agent),
-          "controlling-mode", value);
-      break;
-    case PROP_FORCE_RELAY:
-      g_object_set_property (G_OBJECT (ice->priv->nice_agent),
-          "force-relay", value);
-      break;
     case PROP_ICE_TCP:
       g_object_set_property (G_OBJECT (ice->priv->nice_agent),
           "ice-tcp", value);
@@ -879,29 +928,9 @@ gst_webrtc_ice_get_property (GObject * object, guint prop_id,
   GstWebRTCICE *ice = GST_WEBRTC_ICE (object);
 
   switch (prop_id) {
-    case PROP_STUN_SERVER:
-      if (ice->stun_server)
-        g_value_take_string (value, gst_uri_to_string (ice->stun_server));
-      else
-        g_value_take_string (value, NULL);
-      break;
-    case PROP_TURN_SERVER:
-      if (ice->turn_server)
-        g_value_take_string (value, gst_uri_to_string (ice->turn_server));
-      else
-        g_value_take_string (value, NULL);
-      break;
-    case PROP_CONTROLLER:
-      g_object_get_property (G_OBJECT (ice->priv->nice_agent),
-          "controlling-mode", value);
-      break;
     case PROP_AGENT:
       g_value_set_object (value, ice->priv->nice_agent);
       break;
-    case PROP_FORCE_RELAY:
-      g_object_get_property (G_OBJECT (ice->priv->nice_agent),
-          "force-relay", value);
-      break;
     case PROP_ICE_TCP:
       g_object_get_property (G_OBJECT (ice->priv->nice_agent),
           "ice-tcp", value);
@@ -925,6 +954,11 @@ gst_webrtc_ice_finalize (GObject * object)
 
   _stop_thread (ice);
 
+  if (ice->priv->on_candidate_notify)
+    ice->priv->on_candidate_notify (ice->priv->on_candidate_data);
+  ice->priv->on_candidate = NULL;
+  ice->priv->on_candidate_notify = NULL;
+
   if (ice->turn_server)
     gst_uri_unref (ice->turn_server);
   if (ice->stun_server)
@@ -967,36 +1001,13 @@ gst_webrtc_ice_class_init (GstWebRTCICEClass * klass)
   gobject_class->set_property = gst_webrtc_ice_set_property;
   gobject_class->finalize = gst_webrtc_ice_finalize;
 
-  g_object_class_install_property (gobject_class,
-      PROP_STUN_SERVER,
-      g_param_spec_string ("stun-server", "STUN Server",
-          "The STUN server of the form stun://hostname:port",
-          NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
-
-  g_object_class_install_property (gobject_class,
-      PROP_TURN_SERVER,
-      g_param_spec_string ("turn-server", "TURN Server",
-          "The TURN server of the form turn(s)://username:password@host:port",
-          NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
-
-  g_object_class_install_property (gobject_class,
-      PROP_CONTROLLER,
-      g_param_spec_boolean ("controller", "ICE controller",
-          "Whether the ICE agent is the controller or controlled. "
-          "In WebRTC, the initial offerrer is the ICE controller.", FALSE,
-          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
-
   g_object_class_install_property (gobject_class,
       PROP_AGENT,
       g_param_spec_object ("agent", "ICE agent",
-          "ICE agent in use by this object", NICE_TYPE_AGENT,
+          "ICE agent in use by this object. WARNING! Accessing this property "
-          G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
+          "may have disastrous consequences for the operation of webrtcbin. "
-
+          "Other ICE implementations may not have the same interface.",
-  g_object_class_install_property (gobject_class,
+          NICE_TYPE_AGENT, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
-      PROP_FORCE_RELAY,
-      g_param_spec_boolean ("force-relay", "Force Relay",
-          "Force all traffic to go through a relay.", FALSE,
-          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
   g_object_class_install_property (gobject_class,
       PROP_ICE_TCP,
@@ -1010,16 +1021,6 @@ gst_webrtc_ice_class_init (GstWebRTCICEClass * klass)
           "Whether the agent should use ICE-UDP when gathering candidates",
           TRUE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
-  /**
-   * GstWebRTCICE::on-ice-candidate:
-   * @object: the #GstWebRTCBin
-   * @candidate: the ICE candidate
-   */
-  gst_webrtc_ice_signals[ON_ICE_CANDIDATE_SIGNAL] =
-      g_signal_new ("on-ice-candidate", G_TYPE_FROM_CLASS (klass),
-      G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL,
-      G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_STRING);
-
   /**
    * GstWebRTCICE::add-local-ip-address:
    * @object: the #GstWebRTCICE
@@ -1028,6 +1029,8 @@ gst_webrtc_ice_class_init (GstWebRTCICEClass * klass)
    * Add a local IP address to use for ICE candidate gathering.  If none
    * are supplied, they will be discovered automatically. Calling this signal
    * stops automatic ICE gathering.
+   *
+   * Returns: whether the address could be added.
    */
   gst_webrtc_ice_signals[ADD_LOCAL_IP_ADDRESS_SIGNAL] =
       g_signal_new_class_handler ("add-local-ip-address",

ext/webrtc/gstwebrtcice.h

@@ -81,6 +81,26 @@ gboolean                    gst_webrtc_ice_set_remote_credentials   (GstWebRTCIC
                                                                      gchar * pwd);
 gboolean                    gst_webrtc_ice_add_turn_server          (GstWebRTCICE * ice,
                                                                      const gchar * uri);
+
+void                        gst_webrtc_ice_set_is_controller        (GstWebRTCICE * ice,
+                                                                     gboolean controller);
+gboolean                    gst_webrtc_ice_get_is_controller        (GstWebRTCICE * ice);
+void                        gst_webrtc_ice_set_force_relay          (GstWebRTCICE * ice,
+                                                                     gboolean force_relay);
+void                        gst_webrtc_ice_set_stun_server          (GstWebRTCICE * ice,
+                                                                     const gchar * uri);
+gchar *                     gst_webrtc_ice_get_stun_server          (GstWebRTCICE * ice);
+void                        gst_webrtc_ice_set_turn_server          (GstWebRTCICE * ice,
+                                                                     const gchar * uri);
+gchar *                     gst_webrtc_ice_get_turn_server          (GstWebRTCICE * ice);
+
+typedef void (*GstWebRTCIceOnCandidateFunc) (GstWebRTCICE * ice, guint stream_id, gchar * candidate, gpointer user_data);
+
+void                        gst_webrtc_ice_set_on_ice_candidate     (GstWebRTCICE * ice,
+                                                                     GstWebRTCIceOnCandidateFunc func,
+                                                                     gpointer user_data,
+                                                                     GDestroyNotify notify);
+
 G_END_DECLS
 
 #endif /* __GST_WEBRTC_ICE_H__ */