


transfer::data::destiDataotransfer transfer::data::destination(n)


______________________________________________________________________________

NAME
       transfer::data::destination - Data destination

SYNOPSIS
       package require Tcl  8.4

       package require snit  ?1.0?

       package require transfer::data::destination  ?0.2?

       transfer::data::destination objectName ?options...?

       objectName method ?arg arg ...?

       objectName destroy

       objectName put chunk

       objectName done

       objectName valid msgvar

       objectName receive channel done

_________________________________________________________________

DESCRIPTION
       This  package  provides  objects mainly describing the destination of a
       data transfer. They are also able to initiate the reception of informa-
       tion from a channel into the described destination.

API
       transfer::data::destination objectName ?options...?
              This command creates a new data destination object with an asso-
              ciated Tcl command whose name is objectName.  This  object  com-
              mand  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::data::destination  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



transfer                       0.2                              1





transfer::data::destiDataotransfer transfer::data::destination(n)


              specifications.


   OBJECT METHODS
       objectName destroy
              This  method  destroys  the object. Doing so while the object is
              busy with the reception of information from a channel will cause
              errors  later  on,  when  the  reception  completes and tries to
              access the now missing data structures of the destroyed  object.

       objectName put chunk
              The  main receptor method. Saves the received chunk of data into
              the configured destination. It has to be called for  each  piece
              of data received.

       objectName done
              The secondary receptor method. Finalizes the receiver. It has to
              be called when the receiving channel signals EOF. Afterward nei-
              ther itself nor method put can be called anymore.

       objectName valid msgvar
              This method checks the configuration of the object for validity.
              It returns a boolean flag as result, whose value is True if  the
              object  is  valid,  and  False otherwise. In the latter case the
              variable whose name is stored in msgvar is set to an error  mes-
              sage describing the problem found with the configuration. Other-
              wise this variable is not touched.

       objectName receive channel done
              This method initiates the reception of data from  the  specified
              channel.  The  received  data will be stored into the configured
              destination, via calls to the methods put and  done.   When  the
              reception completes the command prefix done is invoked, with the
              number of received characters appended to it as the  sole  addi-
              tional argument.


   OPTIONS
       All  data  destinations  support the options listed below. It should be
       noted that all are semi-exclusive, each specifying a different type  of
       destination  and associated information. If these options are specified
       more than once then the last option specified is used to actually  con-
       figure the object.

       -channel handle
              This  option  specifies  that  the  destination of the data is a
              channel, and its associated argument is the handle of the  chan-
              nel to write the received data to.

       -file path
              This  option  specifies  that  the  destination of the data is a
              file, and its associated argument is the path  of  the  file  to
              write the received data to.




transfer                       0.2                              2





transfer::data::destiDataotransfer transfer::data::destination(n)


       -variable varname
              This  option  specifies  that  the  destination of the data is a
              variable, and its associated argument contains the name  of  the
              variable  to write the received data to. The variable is assumed
              to be global or namespaced, anchored at the global namespace.

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


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 destination, transfer

CATEGORY
       Transfer module

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




























transfer                       0.2                              3


