transfer::data::destination(n) Data transfer facilities transfer::data::destination(n) 







transfer::data::destination - Data destination








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












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.









  

  
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.

  








All objects created by the ::transfer::data::destination
    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. 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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.










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.



  

  
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.

  

  
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.

  

  
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.

  

  
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.












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.








channel, copy, data destination, transfer








Transfer module








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








  

    0.2
    transfer