


transfer::transmitterData transfer facilitransfer::transmitter(n)


______________________________________________________________________________

NAME
       transfer::transmitter - Data source

SYNOPSIS
       package require Tcl  8.4

       package require snit  ?1.0?

       package require transfer::copy  ?0.2?

       package require transfer::data::source  ?0.2?

       package require transfer::connect  ?0.2?

       package require transfer::transmitter  ?0.2?

       transfer::transmitter objectName ?options...?

       transfer::transmitter stream channel chan host port ?arg...?

       transfer::transmitter stream file path host port ?arg...?

       objectName method ?arg arg ...?

       objectName destroy

       objectName start

       objectName busy

_________________________________________________________________

DESCRIPTION
       This  package  pulls  data sources and connection setup together into a
       combined object for the transmission  of  information  over  a  socket.
       These  objects  understand  all the options from objects created by the
       packages transfer::data::source and transfer::connect.

API
   PACKAGE COMMANDS
       transfer::transmitter objectName ?options...?
              This command creates a new transmitter 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::transmitterData transfer facilitransfer::transmitter(n)


       transfer::transmitter stream channel chan host port ?arg...?
              This method creates a fire-and-forget transfer for the data con-
              tained in the channel chan, starting at the current  seek  loca-
              tion.  The  channel  is configured to use binary translation and
              encoding for the transfer.  The channel is automatically  closed
              when the transfer has completed.

              If  both  host and port are provided an active connection to the
              destination is made. If only a port is specified (with host  the
              empty string) then a passive connection is made instead.

              Any arguments after the port are treated as options and are used
              to configure the internal transmitter object.  See  the  section
              Options  for  a list of the supported options and their meaning.
              Note however that the signature of the command prefix  specified
              for  the  -command  callback  differs from the signature for the
              same option of the transmitter object.  This  callback  is  only
              given  the number of bytes and transfered, and possibly an error
              message. No reference to the internally used transmitter  object
              is made.

              The result returned by the command is the empty string if it was
              set to make an active connection,  and  the  port  the  internal
              transmitter  object  is  listening  on otherwise, i.e when it is
              configured to connect passively.  See also  the  package  trans-
              fer::connect and the description of the method connect for where
              this behaviour comes from.

       transfer::transmitter stream file path host port ?arg...?
              This method is like stream channel, except that  the  data  con-
              tained in the file path is transfered.


   OBJECT COMMAND
       All  objects  created  by  the ::transfer::transmitter command have the
       following 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. Doing so while  a  transmission
              is in progress will cause errors later on, when the transmission
              completes and tries to access the now missing data structures of
              the destroyed object.

       objectName start
              This method initiates the data transmission, setting up the con-
              nection first and then copying the information.  The method will
              throw  an  error if a transmission is already/still in progress.



transfer                       0.2                              2





transfer::transmitterData transfer facilitransfer::transmitter(n)


              I.e. it is not possible to run two transmissions in parallel  on
              a  single object, only in sequence. Multiple transmitter objects
              are needed to manage parallel transfers, one  per  transmission.
              Errors  will  also  be  thrown  if the configuration of the data
              source is invalid, or if no completion callback was specified.

              The result returned by the method is the  empty  string  for  an
              object configured to make an active connection, and the port the
              object is listening on otherwise, i.e when it is  configured  to
              connect  passively.   See also the package transfer::connect and
              the description of the method connect for where  this  behaviour
              comes from.

       objectName busy
              This  method returns a boolean value telling us whether a trans-
              mission is in progress (True), or not (False).


   OPTIONS
       All transmitter objects support the union of the options  supported  by
       their  connect  and data source components, plus two of their own.  See
       also the documentation  for  the  packages  transfer::data::source  and
       transfer::connect.

       -blocksize int
              This  option  specifies the size of the chunks to be transmitted
              in one block. Usage is optional, its default value is 1024.

       -command cmdprefix
              This option specifies the command to invoke when  the  transmis-
              sion of the information has been completed.  The arguments given
              to this command are the same as given to the completion callback
              of the command transfer::copy::do provided by the package trans-
              fer::copy.

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



transfer                       0.2                              3





transfer::transmitterData transfer facilitransfer::transmitter(n)


       -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 estab-
              lished, but before the callback is invoked (See method connect).

       -string text
              This  option specifies that the source of the data is an immedi-
              ate string, and its associated argument contains the  string  in
              question.

       -channel handle
              This  option specifies that the source of the data is a channel,
              and its associated argument is the handle of  the  channel  con-
              taining the data.

       -file path
              This option specifies that the source of the data is a file, and
              its associated argument is the path of the file  containing  the
              data.

       -variable varname
              This  option  specifies  that the source of the data is a string
              stored in a variable, and its associated argument  contains  the
              name  of the variable in question. The variable is assumed to be
              global or namespaced, anchored at the global namespace.

       -size int
              This option specifies the size  of  the  data  transfer.  It  is
              optional  and  defaults  to  -1. This value, and any other value
              less than zero signals to transfer all the data from the source.



transfer                       0.2                              4





transfer::transmitterData transfer facilitransfer::transmitter(n)


       -progress command
              This  option,  if specified, defines a command to be invoked for
              each chunk of bytes transmitted, allowing the  user  to  monitor
              the  progress  of  the transmission of the data. The callback is
              always invoked with one additional argument, the number of bytes
              transmitted so far.


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::transmitter T -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
       channel, copy, data source, secure, ssl, tls, transfer, transmitter

CATEGORY
       Transfer module

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




















transfer                       0.2                              5


