Provided by: tcllib_1.15-dfsg-2_all bug

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 information from a channel into  the  described
       destination.

API

       transfer::data::destination objectName ?options...?
              This  command  creates a new data destination 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::data::destination  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. 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  neither  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  message  describing  the problem found with the configuration. Otherwise
              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
              additional 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 configure 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 channel 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.

       -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://sourceforge.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>