[glib/mcatanzaro/validation-flags: 3/3] gsocketclient: deprecate tls-validation-flags property

[Michael Catanzaro <mcatanzaro src gnome org>]

commit f17202bf2342a4e72f9d5ee13c160ffdd5a6a90e
Author: Michael Catanzaro <mcatanzaro redhat com>
Date:   Wed Aug 4 15:20:41 2021 -0500

    gsocketclient: deprecate tls-validation-flags property
    
    It doesn't work as expected, and you shouldn't be trying to use it
    anyway.

 gio/gsocketclient.c | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)
---
diff --git a/gio/gsocketclient.c b/gio/gsocketclient.c
index 62b1afbcd..738d6a6e4 100644
--- a/gio/gsocketclient.c
+++ b/gio/gsocketclient.c
@@ -697,7 +697,11 @@ g_socket_client_get_tls_validation_flags (GSocketClient *client)
  * Sets the TLS validation flags used when creating TLS connections
  * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.
  *
+ * See #GSocketClient:tls-validation-flags for more information.
+ *
  * Since: 2.28
+ *
+ * Deprecated: 2.70. Do not attempt to ignore validation errors.
  */
 void
 g_socket_client_set_tls_validation_flags (GSocketClient        *client,
@@ -916,6 +920,26 @@ g_socket_client_class_init (GSocketClientClass *class)
                                                         G_PARAM_CONSTRUCT |
                                                         G_PARAM_READWRITE |
                                                         G_PARAM_STATIC_STRINGS));
+
+  /**
+   * GSocketClient:tls-validation-flags:
+   *
+   * The TLS validation flags used when creating TLS connections. The
+   * default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.
+   *
+   * GLib guarantees that if certificate verification fails, at least one
+   * flag will be set, but it does not guarantee that all possible flags
+   * will be set. Accordingly, you may not safely decide to ignore any
+   * particular type of error. For example, it would be incorrect to mask
+   * %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates,
+   * because this could potentially be the only error flag set even if
+   * other problems exist with the certificate. Therefore, there is no
+   * safe way to use this property. This is not a horrible problem,
+   * though, because you should not be attempting to ignore validation
+   * errors anyway.
+   *
+   * Deprecated: 2.70. Do not attempt to ignore validation errors.
+   */
   g_object_class_install_property (gobject_class, PROP_TLS_VALIDATION_FLAGS,
                                   g_param_spec_flags ("tls-validation-flags",
                                                       P_("TLS validation flags"),
@@ -924,7 +948,8 @@ g_socket_client_class_init (GSocketClientClass *class)
                                                       G_TLS_CERTIFICATE_VALIDATE_ALL,
                                                       G_PARAM_CONSTRUCT |
                                                       G_PARAM_READWRITE |
-                                                      G_PARAM_STATIC_STRINGS));
+                                                      G_PARAM_STATIC_STRINGS |
+                                                      G_PARAM_DEPRECATED));
 
   /**
    * GSocketClient:proxy-resolver: