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







transfer::connect - Connection setup








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












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.













  

  
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.

  










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



  

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











  

  
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.

  

  
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.

  







  

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

  

  
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.

  












Connection objects support the set of options listed below.



  

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







  

  
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.

  

  
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.







  

  
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.

  

  
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.

  

  
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.

  

  

  

  

  

  

  
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).












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 ...


    ...









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.








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








Transfer module








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








  

    0.2
    transfer