


transfer::copy(n)    Data transfer facilities   transfer::copy(n)


______________________________________________________________________________

NAME
       transfer::copy - Data transfer foundation

SYNOPSIS
       package require Tcl  8.4

       package require transfer::copy  ?0.2?

       transfer::copy::do chan|string data outchannel ?options...?

       transfer::copy::chan channel outchannel ?options...?

       transfer::copy::string string outchannel ?options...?

       transfer::copy::doChan channel outchannel optvar

       transfer::copy::doString string outchannel optvar

       transfer::copy::options outchannel optionlist optvar

_________________________________________________________________

DESCRIPTION
       This  package  provides  a  number  of commands for the asynchronous of
       information contained in either a string or channel. The main point  of
       this  package  is  that  the commands here provide a nicer callback API
       than the builtin command fcopy, making the use of these facilities sim-
       pler than the builtin.

API
       transfer::copy::do chan|string data outchannel ?options...?
              This  command  transfers the information in data to the outchan-
              nel, according to the options. The type of  the  information  in
              data is determined by the first argument.

              The options available to this command are the same as are avail-
              able  to  the  command  transfer::copy::options,  and  explained
              there.

              chan   The  argument  data  contains the handle of a channel and
                     the actual infomration to  transfer  is  read  from  that
                     channel.

              string The  argument  data  contains  a  string  and this is the
                     information to be transfered.

       transfer::copy::chan channel outchannel ?options...?
              This command is a shorter and more direct form for  the  command
              transfer::copy::do chan.

       transfer::copy::string string outchannel ?options...?
              This  command  is a shorter and more direct form for the command



transfer                       0.2                              1





transfer::copy(n)    Data transfer facilities   transfer::copy(n)


              transfer::copy::do string.

       transfer::copy::doChan channel outchannel optvar
              This command is an alternate form of transfer::copy::chan  which
              reads  its  options  out  of  the array variable named by optvar
              instead of from a variable length argument list.

       transfer::copy::doString string outchannel optvar
              This command is  an  alternate  form  of  transfer::copy::string
              which  reads its options out of the array variable named by opt-
              var instead of from a variable length argument list.

       transfer::copy::options outchannel optionlist optvar
              This command is the option processor used by  all  the  commands
              above  which  read their options from a variable length argument
              list. It first reads default settings from  the  channel  handle
              outchannel, then processes the list of options in optionlist, at
              last stores the results in the array variable named  by  optvar.
              The  contents of that variable are in a format which is directly
              understood by all the commands above which  read  their  options
              out of an array variable.

              The recognized options are:

              -blocksize int
                     This  option specifies the size of the chunks to transfer
                     in one operation. It is  optional  and  defaults  to  the
                     value  of  -buffersize as configured for the output chan-
                     nel.

                     If specified its  value  has  to  be  an  integer  number
                     greater than zero.

              -command commandprefix
                     This  option  specifies  the  completion  callback of the
                     operation. This option has to be specified. An error will
                     be  thrown  if it is not, or if the empty list was speci-
                     fied as argument to it.

                     Its value has to be a command prefix, i.e. a  list  whose
                     first  word  is the command to execute, followed by words
                     containing fixed arguments. When the callback is  invoked
                     one  or two additional arguments are appended to the pre-
                     fix. The first argument is the number of bytes which were
                     transfered. The optional second argument is an error mes-
                     sage and added if and only if an error occured during the
                     the transfer.

              -progress commandprefix
                     This option specifies the progress callback of the opera-
                     tion. It is optional and defaults to the empty list. This
                     last  possibility  signals that no feedback was asked for
                     and disabled it.




transfer                       0.2                              2





transfer::copy(n)    Data transfer facilities   transfer::copy(n)


                     Its value has to be a command prefix, see above, -command
                     for  a  more  detailed  explanation. When the callback is
                     invoked a single additional arguments is appended to  the
                     prefix.  This  argument is the number of bytes which were
                     transfered so far.

              -size int
                     This option specifies the number of bytes  to  read  from
                     the  input data and transfer. It is optional and defaults
                     to "Transfer everything".  Its value has to be an integer
                     number and any value less than zero has the same meaning,
                     i.e. to transfer all available data. Any other  value  is
                     the amount of bytes to transfer.

                     All transfer commands will throw error an when their user
                     tries to transfer more data  than  is  available  in  the
                     input.  This  happens immediately, before the transfer is
                     actually started, should the input be a string. Otherwise
                     the, i.e. for a channel as input, the error is thrown the
                     moment the underflow condition is actually detected.

              -encoding encodingname

              -eofchar eofspec

              -translation transspec
                     These options are the  same  as  are  recognized  by  the
                     builtin  command  fconfigure and provide the settings for
                     the output channel which are  to  be  active  during  the
                     transfer,  and only then. I.e. the settings of the output
                     channel before the transfer are saved,  and  restored  at
                     the end of a transfer, regardless of its success or fail-
                     ure. None of these options are required, and they default
                     to the settings of the output channel if not specified.


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

CATEGORY
       Transfer module

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






transfer                       0.2                              3


