transfer::connect(n)       Data transfer facilities       transfer::connect(n)



______________________________________________________________________________

NAME
       transfer::connect - Connection setup

SYNOPSIS
       package require Tcl  8.4

       package require snit  ?1.0?

       package require transfer::connect  ?0.2?

       transfer::connect objectName ?options...?

       objectName method ?arg arg ...?

       objectName destroy

       objectName connect command

_________________________________________________________________

DESCRIPTION
       This package provides objects holding enough information to enable them
       to either actively connect to a counterpart, or to passively wait for a
       connection from said counterpart.  I.e. any object created by this
       packages is always in one of two complementary modes, called active
       (the object initiates the connection) and passive (the object receives
       the connection).

       Of the two objects in a connecting pair one has to be configured for
       active mode, and the other then has to be configured for passive mode.
       This establishes which of the two partners connects to whom (the active
       to the other), or, who is waiting on whom (the passive on the other).
       Note that this is completely independent of the direction of any data
       transmission using the connection after it has been established.  An
       active object can, after establishing the connection, either transmit
       or receive data. Equivalently the passive object can do the same after
       the waiting for its partner has ended.

API
   PACKAGE COMMANDS
       transfer::connect objectName ?options...?
              This command creates a new connection object with an associated
              Tcl command whose name is objectName.  This object command is
              explained in full detail in the sections Object command and
              Object methods. The set of supported options is explained in
              section Options.

              The object command will be created under the current namespace
              if the objectName is not fully qualified, and in the specified
              namespace otherwise.  The fully qualified name of the object
              command is returned as the result of the command.

   OBJECT COMMAND
       All objects created by the ::transfer::connect command have the
       following general form:

       objectName method ?arg arg ...?
              The method method and its arg'uments determine the exact
              behavior of the command.  See section Object methods for the
              detailed specifications.

   OBJECT METHODS
       objectName destroy
              This method destroys the object.  This is safe to do for an
              active object when a connection has been started, as the
              completion callback is synchronous.  For a passive object
              currently waiting for its partner to establish the connection
              however this is not safe and will cause errors later on, when
              the connection setup completes and tries to access the now
              missing data structures of the destroyed object.

       objectName connect command
              This method starts the connection setup per the configuration of
              the object. When the connection is established the callback
              command will be invoked with one additional argument, the
              channel handle of the socket over which data can be transfered.

              The detailed behaviour of the method depends on the configured
              mode.

              active The connection setup is done synchronously. The object
                     waits until the connection is established. The method
                     returns the empty string as its result.

              passive
                     The connection setup is done asynchronously. The method
                     returns immediately after a listening socket has been set
                     up. The connection will be established in the background.
                     The method returns the port number of the listening
                     socket, for use by the caller. One important use is the
                     transfer of this information to the counterpart so that
                     it knows where it has to connect to.

                     This is necessary as the object might have been
                     configured for port 0, allowing the operating system to
                     choose the actual port it will listen on.

                     The listening port is closed immediately when the
                     connection was established by the partner, to keep the
                     time interval small within which a third party can
                     connect to the port too.  Even so it is recommended to
                     use additional measures in the protocol outside of the
                     connect and transfer object to ensure that a connection
                     is not used with an unidentified/unauthorized partner One
                     possibility for this is the use of SSL/TLS.  See the
                     option -socketcmd and section Secure connections for
                     information on how to do this.

   OPTIONS
       Connection objects support the set of options listed below.

       -mode mode
              This option specifies the mode the object is in. It is optional
              and defaults to active mode. The two possible modes are:

              active In this mode the two options -host and -port are relevant
                     and specify the host and TCP port the object has to
                     connect to. The host is given by either name or IP
                     address.

              passive
                     In this mode the option -host has no relevance and is
                     ignored should it be configured.  The only option the
                     object needs is -port, and it specifies the TCP port on
                     which the listening socket is opened to await the
                     connection from the partner.

       -host hostname-or-ipaddr
              This option specifies the host to connect to in active mode,
              either by name or ip-address. An object configured for passive
              mode ignores this option.

       -port int
              For active mode this option specifies the port the object is
              expected to connect to. For passive mode however it is the port
              where the object creates the listening socket waiting for a
              connection. It defaults to 0, which allows the OS to choose the
              actual port to listen on.

       -socketcmd command
              This option allows the user to specify which command to use to
              open a socket. The default is to use the builtin ::socket. Any
              compatible with that command is allowed.

              The envisioned main use is the specfication of tls::socket. I.e.
              this option allows the creation of secure transfer channels,
              without making this package explicitly dependent on the tls
              package.

              See also section Secure connections.

       -encoding encodingname

       -eofchar eofspec

       -translation transspec
              These options are the same as are recognized by the builtin
              command fconfigure. They provide the configuration to be set for
              the channel between the two partners after it has been
              established, but before the callback is invoked (See method
              connect).

SECURE CONNECTIONS
       One way to secure connections made by objects of this package is to
       require the package tls and then configure the option -socketcmd to
       force the use of command tls::socket to open the socket.

                  # Load and initialize tls
                  package require tls
                  tls::init -cafile /path/to/ca/cert -keyfile ...

                  # Create a connector with secure socket setup,
                  transfer::connect C -socketcmd tls::socket ...
                  ...


BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will undoubtedly contain
       bugs and other problems.  Please report such in the category transfer
       of the Tcllib SF Trackers
       [http://sourceforge.net/tracker/?group_id=12883].  Please also report
       any ideas for enhancements you may have for either package and/or
       documentation.

KEYWORDS
       active, channel, connection, passive, secure, ssl, tls, transfer

CATEGORY
       Transfer module

COPYRIGHT
       Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>




transfer                              0.2                 transfer::connect(n)
