PRELIMINARY
SYNOPSIS
        int tls_init_connection(object ob)
        int tls_init_connection(object ob, string fun, string|object fob,
                                mixed extra...)
        int tls_init_connection(object ob, closure fun, mixed extra...)

DESCRIPTION
        tls_init_connection() tries to start a TLS secured connection to 
        the interactive object <ob> (or this_object() if <ob> is not given).

        Result:
          errorcode < 0: unsuccessful, use tls_error() to get an useful
                         description of the error
             number > 0: the secure connection is still being set up in the
                          background
            number == 0: the secure connection is active.
        
        OpenSSL only:

            If the callback <fun>/<fun>:<fob> is specified, it will be called
            once the fate of the secure connection has been determined. The
            first argument will be the return code from the handshake
            (errorcode < 0 on failure, or 0 on success), followed by the
            interactive object <ob> and any <extra> arguments.

        If the TLS setup fails, it is not necessary to call
        tls_deinit_connection().

        IMPORTANT: During the TLS handshake nothing else must be sent
        to the client! For the most cases (TLS-capable clients logging in)
        this means that the TLS handshake is the first and only thing the
        client gets to see while the handshake is in progress.

        The driver automatically suppresses the printing of the prompt
        while the TLS handshake is in progress.

        If tls_init_connection() is called in the master::connect() function,
        the driver will either call the set callback in place of logon(), or
        if not callback has been set, delay the call of logon() until the
        state of the connection is clear.

HISTORY
        Introduced in LDMud 3.3.474 and following, backported to 3.2.11.
        LDMud 3.2.13/3.3.713 streamlined the handling of secure connections
        during logon.

SEE ALSO
        tls_deinit_connection(E), tls_error(E), tls_query_connection_state(E),
        tls_query_connection_info(E), tls_available(E),
        tls_check_certificate(E), tls_refresh_certs(E), connect(M), logon(A)