From b75dd395bad3a4109a7ebd1d8c4c3356f8797462 Mon Sep 17 00:00:00 2001 From: Michael Catanzaro Date: Wed, 13 Nov 2019 20:53:37 -0600 Subject: [PATCH] gtlsconnection: clarify handshake() documentation This tries to clarify some confusing aspects of the g_tls_connection_handshake() that can trip up experienced developers. --- gio/gtlsconnection.c | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/gio/gtlsconnection.c b/gio/gtlsconnection.c index 2e431ae7e..5bdea96e5 100644 --- a/gio/gtlsconnection.c +++ b/gio/gtlsconnection.c @@ -887,15 +887,16 @@ g_tls_connection_get_negotiated_protocol (GTlsConnection *conn) * * On the client side, it is never necessary to call this method; * although the connection needs to perform a handshake after - * connecting (or after sending a "STARTTLS"-type command) and may - * need to rehandshake later if the server requests it, + * connecting (or after sending a "STARTTLS"-type command), * #GTlsConnection will handle this for you automatically when you try - * to send or receive data on the connection. However, you can call - * g_tls_connection_handshake() manually if you want to know for sure - * whether the initial handshake succeeded or failed (as opposed to - * just immediately trying to write to @conn's output stream, in which - * case if it fails, it may not be possible to tell if it failed - * before or after completing the handshake). + * to send or receive data on the connection. You can call + * g_tls_connection_handshake() manually if you want to know whether + * the initial handshake succeeded or failed (as opposed to just + * immediately trying to use @conn to read or write, in which case, + * if it fails, it may not be possible to tell if it failed before or + * after completing the handshake), but beware that servers may reject + * client authentication after the handshake has completed, so a + * successful handshake does not indicate the connection will be usable. * * Likewise, on the server side, although a handshake is necessary at * the beginning of the communication, you do not need to call this @@ -910,6 +911,10 @@ g_tls_connection_get_negotiated_protocol (GTlsConnection *conn) * nondestructive so as to preserve compatibility with code written for * older versions of GLib. * + * When using a #GTlsConnection created by #GSocketClient, the + * #GSocketClient performs the initial handshake, so calling this + * function manually is not recommended. + * * #GTlsConnection::accept_certificate may be emitted during the * handshake. *