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

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 99df2ee313149db3cce20b42d1562c9050773ee7
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 | 29 ++++++++++++++++++++++++++++-
 gio/gsocketclient.h |  4 ++--
 2 files changed, 30 insertions(+), 3 deletions(-)
---
diff --git a/gio/gsocketclient.c b/gio/gsocketclient.c
index 62b1afbcd..6952d9210 100644
--- a/gio/gsocketclient.c
+++ b/gio/gsocketclient.c
@@ -682,6 +682,8 @@ g_socket_client_set_tls (GSocketClient *client,
  * Returns: the TLS validation flags
  *
  * Since: 2.28
+ *
+ * Deprecated: 2.70. Do not attempt to ignore validation errors.
  */
 GTlsCertificateFlags
 g_socket_client_get_tls_validation_flags (GSocketClient *client)
@@ -697,7 +699,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 +922,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 +950,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:
diff --git a/gio/gsocketclient.h b/gio/gsocketclient.h
index f0153450d..1b532f8b0 100644
--- a/gio/gsocketclient.h
+++ b/gio/gsocketclient.h
@@ -110,9 +110,9 @@ gboolean                g_socket_client_get_tls                         (GSocket
 GLIB_AVAILABLE_IN_2_28
 void                    g_socket_client_set_tls                         (GSocketClient        *client,
                                                                         gboolean              tls);
-GLIB_AVAILABLE_IN_2_28
+GLIB_DEPRECATED_IN_2_70
 GTlsCertificateFlags    g_socket_client_get_tls_validation_flags        (GSocketClient        *client);
-GLIB_AVAILABLE_IN_2_28
+GLIB_DEPRECATED_IN_2_70
 void                    g_socket_client_set_tls_validation_flags        (GSocketClient        *client,
                                                                         GTlsCertificateFlags  flags);
 GLIB_AVAILABLE_IN_2_36