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



______________________________________________________________________________

NAME
       transfer::data::source - 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?

       transfer::data::source objectName ?options...?

       objectName method ?arg arg ...?

       objectName destroy

       objectName type

       objectName data

       objectName size

       objectName valid msgvar

       objectName transmit channel blocksize done

_________________________________________________________________

DESCRIPTION
       This package provides objects mainly describing the origin of some data
       to transfer. They are also able to initiate transfers of the described
       information to a channel using the foundation package transfer::copy.

API
   PACKAGE COMMANDS
       transfer::data::source objectName ?options...?
              This command creates a new data source 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::source 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 a transfer
              initiated by the object is active is safe as all data required
              for the transfer itself was copied, and the completion of the
              transfer will not try to access the initiating object anymore.
              i.e. the transfer is completely separate from the source object
              itself.

       objectName type
              This method returns a string describing the type of the data the
              object is refering to. The possible values and their meanings
              are:

              undefined
                     No data was specified at all, or it was specified
                     incompletely. The object does not know the type.

              string The data to transfer is contained in a string.

              channel
                     The data to transfer is contained in a channel.

       objectName data
              This method returns a value depending on the type of the data
              the object refers to, through which the data can be accessed.
              The method throws an error if the type is undefined. For type
              string the returned result is the data itself, whereas for type
              channel the returned result is the handle of the channel
              containing the data.

       objectName size
              This method returns a value depending on the type of the data
              the object refers to, the size of the data.  The method throws
              an error if the type is undefined. Return of a negative value
              signals that the object is unable to determine an absolute size
              upfront (like for data in a channel).

       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 transmit channel blocksize done
              This method initiates a transfer of the referenced data to the
              specified channel.  When the transfer completes the command
              prefix done is invoked, per the rules for the option -command of
              command transfer::copy::do in the package transfer::copy.  The
              blocksize specifies the size of the chunks to transfer in one
              go. See the option -blocksize of command transfer::copy::do in
              the package transfer::copy.

   OPTIONS
       All data sources support the options listed below. It should be noted
       that the first four options are semi-exclusive, each specifying a
       different type of data source and associated content. If these options
       are specified more than once then the last option specified is used to
       actually configure the object.

       -string text
              This option specifies that the source of the data is an
              immediate 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
              containing 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.

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

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

CATEGORY
       Transfer module

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




transfer                              0.2            transfer::data::source(n)
