more documentation and logic simplification

include/aws/io/tls_channel_handler.h

@@ -88,6 +88,8 @@ struct aws_tls_ctx {
 /**
  * Invoked upon completion of the TLS handshake. If successful error_code will be AWS_OP_SUCCESS, otherwise
  * the negotiation failed and immediately after this function is invoked, the channel will be shutting down.
+ *
+ * NOTE: When using SecItem, the handler and slot will be related to sockets and not tls.
  */
 typedef void(aws_tls_on_negotiation_result_fn)(
     struct aws_channel_handler *handler,

source/channel_bootstrap.c

@@ -130,7 +130,7 @@ struct client_connection_args {
     struct aws_event_loop *requested_event_loop;
 
     /*
-     * Apple network framework's establishment of a network connection combines both socket and TLS related
+     * Apple network framework's establishment of a network connection combines both TCP and TLS related
      * operations into a singular connection callback. This is used to store a previously received
      * TLS error_code that can be reported at a later time.
      */
@@ -488,22 +488,22 @@ static void s_on_client_channel_on_setup_completed(struct aws_channel *channel,
         }
 
         if (connection_args->channel_data.use_tls) {
-/* AWS_USE_SECITEM is using Apple Network Framework's implementation of TLS handling.
- * The TCP and TLS handshake are both handled by the network parameters and its options and verification
- * block. We do not need to set up a separate TLS slot in the channel for iOS. */
 #if defined(AWS_USE_SECITEM)
+            /* AWS_USE_SECITEM is using Apple Network Framework's implementation of TLS handling.
+             * The TCP and TLS handshakes are both handled by the network parameters, its options, and verification
+             * block. We do not need to set up a separate TLS slot in the channel when using SecItem. We only get to
+             * here if a TLS connection is successfully established so we trigger a success using the TLS handshake
+             * completion path to provide access to the server name and protocol if one exists. */
             s_tls_client_on_negotiation_result(socket_channel_handler, socket_slot, err_code, connection_args);
             return;
-#endif
-#if !defined(AWS_USE_SECITEM)
+#endif /* AWS_USE_SECITEM */
             /* we don't want to notify the user that the channel is ready yet, since tls is still negotiating, wait
              * for the negotiation callback and handle it then.*/
             if (s_setup_client_tls(connection_args, channel)) {
                 err_code = aws_last_error();
                 goto error;
             }
             return;
-#endif
         } else {
             s_connection_args_setup_callback(connection_args, AWS_OP_SUCCESS, channel);
         }