


transfer::connect(n) Data transfer facilitiestransfer::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.




transfer                       0.2                              1





transfer::connect(n) Data transfer facilitiestransfer::connect(n)


   OBJECT COMMAND
       All objects created by the ::transfer::connect command have the follow-
       ing general form:

       objectName method ?arg arg ...?
              The method method and its arg'uments determine the exact  behav-
              ior 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 comple-
              tion 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 struc-
              tures 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 com-
              mand 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  config-
                     ured  for port 0, allowing the operating system to choose
                     the actual port it will listen on.

                     The listening port is closed immediately when the connec-
                     tion  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 addi-
                     tional 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 possi-
                     bility  for  this  is the use of SSL/TLS.  See the option



transfer                       0.2                              2





transfer::connect(n) Data transfer facilitiestransfer::connect(n)


                     -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 con-
                     nect 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 connec-
                     tion 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 con-
              nection. 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 com-
              mand  fconfigure.  They  provide the configuration to be set for
              the  channel  between  the  two  partners  after  it  has   been



transfer                       0.2                              3





transfer::connect(n) Data transfer facilitiestransfer::connect(n)


              established, but before the callback is invoked (See method con-
              nect).


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://source-
       forge.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                              4


