luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-26 15:36:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

gtlsconnection: clarify handshake() documentation

Browse Source 
This tries to clarify some confusing aspects of the
g_tls_connection_handshake() that can trip up experienced developers.
This commit is contained in:
Michael Catanzaro 2019-11-13 20:53:37 -06:00
parent b43bfcaa68
commit b75dd395ba
1 changed files with 13 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
gio/gtlsconnection.c
View File

@ -887,15 +887,16 @@ g_tls_connection_get_negotiated_protocol (GTlsConnection *conn)
* *
* On the client side, it is never necessary to call this method; * On the client side, it is never necessary to call this method;
* although the connection needs to perform a handshake after * although the connection needs to perform a handshake after
* connecting (or after sending a "STARTTLS"-type command) and may * connecting (or after sending a "STARTTLS"-type command),
* need to rehandshake later if the server requests it,
* #GTlsConnection will handle this for you automatically when you try * #GTlsConnection will handle this for you automatically when you try
* to send or receive data on the connection. However, you can call * to send or receive data on the connection. You can call
* g_tls_connection_handshake() manually if you want to know for sure * g_tls_connection_handshake() manually if you want to know whether
* whether the initial handshake succeeded or failed (as opposed to * the initial handshake succeeded or failed (as opposed to just
* just immediately trying to write to @conn's output stream, in which * immediately trying to use @conn to read or write, in which case,
* case if it fails, it may not be possible to tell if it failed * if it fails, it may not be possible to tell if it failed before or
* before or after completing the handshake). * 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 * Likewise, on the server side, although a handshake is necessary at
* the beginning of the communication, you do not need to call this * 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 * nondestructive so as to preserve compatibility with code written for
* older versions of GLib. * 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 * #GTlsConnection::accept_certificate may be emitted during the
* handshake. * handshake.
* *