1transfer::data::destination(Dna)ta transfer facilititersansfer::data::destination(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       transfer::data::destination - Data destination
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require snit  ?1.0?
14
15       package require transfer::data::destination  ?0.2?
16
17       transfer::data::destination objectName ?options...?
18
19       objectName method ?arg arg ...?
20
21       objectName destroy
22
23       objectName put chunk
24
25       objectName done
26
27       objectName valid msgvar
28
29       objectName receive channel done
30
31______________________________________________________________________________
32

DESCRIPTION

34       This  package  provides  objects mainly describing the destination of a
35       data transfer. They are also able to initiate the reception of informa‐
36       tion from a channel into the described destination.
37

API

39       transfer::data::destination objectName ?options...?
40              This command creates a new data destination object with an asso‐
41              ciated Tcl command whose name is objectName.  This  object  com‐
42              mand  is explained in full detail in the sections Object command
43              and Object methods. The set of supported options is explained in
44              section Options.
45
46              The  object  command will be created under the current namespace
47              if the objectName is not fully qualified, and in  the  specified
48              namespace  otherwise.   The  fully  qualified name of the object
49              command is returned as the result of the command.
50
51   OBJECT COMMAND
52       All objects created by the ::transfer::data::destination  command  have
53       the following general form:
54
55       objectName method ?arg arg ...?
56              The  method method and its arg'uments determine the exact behav‐
57              ior of the command.  See section Object methods for the detailed
58              specifications.
59
60   OBJECT METHODS
61       objectName destroy
62              This  method  destroys  the object. Doing so while the object is
63              busy with the reception of information from a channel will cause
64              errors  later  on,  when  the  reception  completes and tries to
65              access the now missing data structures of the destroyed object.
66
67       objectName put chunk
68              The main receptor method. Saves the received chunk of data  into
69              the  configured  destination. It has to be called for each piece
70              of data received.
71
72       objectName done
73              The secondary receptor method. Finalizes the receiver. It has to
74              be called when the receiving channel signals EOF. Afterward nei‐
75              ther itself nor method put can be called anymore.
76
77       objectName valid msgvar
78              This method checks the configuration of the object for validity.
79              It  returns a boolean flag as result, whose value is True if the
80              object is valid, and False otherwise. In  the  latter  case  the
81              variable  whose name is stored in msgvar is set to an error mes‐
82              sage describing the problem found with the configuration. Other‐
83              wise this variable is not touched.
84
85       objectName receive channel done
86              This  method  initiates the reception of data from the specified
87              channel. The received data will be stored  into  the  configured
88              destination,  via  calls  to the methods put and done.  When the
89              reception completes the command prefix done is invoked, with the
90              number  of  received characters appended to it as the sole addi‐
91              tional argument.
92
93   OPTIONS
94       All data destinations support the options listed below.  It  should  be
95       noted  that all are semi-exclusive, each specifying a different type of
96       destination and associated information. If these options are  specified
97       more  than once then the last option specified is used to actually con‐
98       figure the object.
99
100       -channel handle
101              This option specifies that the destination  of  the  data  is  a
102              channel,  and its associated argument is the handle of the chan‐
103              nel to write the received data to.
104
105       -file path
106              This option specifies that the destination  of  the  data  is  a
107              file,  and  its  associated  argument is the path of the file to
108              write the received data to.
109
110       -variable varname
111              This option specifies that the destination  of  the  data  is  a
112              variable,  and  its associated argument contains the name of the
113              variable to write the received data to. The variable is  assumed
114              to be global or namespaced, anchored at the global namespace.
115
116       -progress command
117              This  option,  if specified, defines a command to be invoked for
118              each chunk of bytes received, allowing the user to  monitor  the
119              progress  of  the  reception of the data. The callback is always
120              invoked with  one  additional  argument,  the  number  of  bytes
121              received so far.
122

BUGS, IDEAS, FEEDBACK

124       This  document,  and the package it describes, will undoubtedly contain
125       bugs and other problems.  Please report such in the  category  transfer
126       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
127       also report any ideas for enhancements you may have for either  package
128       and/or documentation.
129
130       When proposing code changes, please provide unified diffs, i.e the out‐
131       put of diff -u.
132
133       Note further that  attachments  are  strongly  preferred  over  inlined
134       patches.  Attachments  can  be  made  by  going to the Edit form of the
135       ticket immediately after its creation, and  then  using  the  left-most
136       button in the secondary navigation bar.
137

KEYWORDS

139       channel, copy, data destination, transfer
140

CATEGORY

142       Transfer module
143
145       Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
146
147
148
149
150tcllib                                0.2       transfer::data::destination(n)
Impressum