1transfer::data::source(n) Data transfer facilities transfer::data::source(n)
2______________________________________________________________________________
6
8 transfer::data::source - Data source
9
11 package require Tcl 8.4
12 package require snit ?1.0?
14 package require transfer::copy ?0.2?
16 package require transfer::data::source ?0.2?
18 transfer::data::source objectName ?options...?
20 objectName method ?arg arg ...?
22 objectName destroy
24 objectName type
26 objectName data
28 objectName size
30 objectName valid msgvar
32 objectName transmit channel blocksize done
34______________________________________________________________________________
36
38 This package provides objects mainly describing the origin of some data
39 to transfer. They are also able to initiate transfers of the described
40 information to a channel using the foundation package transfer::copy.
41
43 PACKAGE COMMANDS
44 transfer::data::source objectName ?options...?
45 This command creates a new data source object with an associated
46 Tcl command whose name is objectName. This object command is
47 explained in full detail in the sections Object command and
48 Object methods. The set of supported options is explained in
49 section Options.
50 The object command will be created under the current namespace
52 if the objectName is not fully qualified, and in the specified
53 namespace otherwise. The fully qualified name of the object
54 command is returned as the result of the command.
55 OBJECT COMMAND
57 All objects created by the ::transfer::data::source command have the
58 following general form:
59 objectName method ?arg arg ...?
61 The method method and its arg'uments determine the exact behav‐
62 ior of the command. See section Object methods for the detailed
63 specifications.
64 OBJECT METHODS
66 objectName destroy
67 This method destroys the object. Doing so while a transfer ini‐
68 tiated by the object is active is safe as all data required for
69 the transfer itself was copied, and the completion of the trans‐
70 fer will not try to access the initiating object anymore. i.e.
71 the transfer is completely separate from the source object
72 itself.
73 objectName type
75 This method returns a string describing the type of the data the
76 object is refering to. The possible values and their meanings
77 are:
78 undefined
80 No data was specified at all, or it was specified incom‐
81 pletely. The object does not know the type.
82 string The data to transfer is contained in a string.
84 channel
86 The data to transfer is contained in a channel.
87 objectName data
89 This method returns a value depending on the type of the data
90 the object refers to, through which the data can be accessed.
91 The method throws an error if the type is undefined. For type
92 string the returned result is the data itself, whereas for type
93 channel the returned result is the handle of the channel con‐
94 taining the data.
95 objectName size
97 This method returns a value depending on the type of the data
98 the object refers to, the size of the data. The method throws
99 an error if the type is undefined. Return of a negative value
100 signals that the object is unable to determine an absolute size
101 upfront (like for data in a channel).
102 objectName valid msgvar
104 This method checks the configuration of the object for validity.
105 It returns a boolean flag as result, whose value is True if the
106 object is valid, and False otherwise. In the latter case the
107 variable whose name is stored in msgvar is set to an error mes‐
108 sage describing the problem found with the configuration. Other‐
109 wise this variable is not touched.
110 objectName transmit channel blocksize done
112 This method initiates a transfer of the referenced data to the
113 specified channel. When the transfer completes the command pre‐
114 fix done is invoked, per the rules for the option -command of
115 command transfer::copy::do in the package transfer::copy. The
116 blocksize specifies the size of the chunks to transfer in one
117 go. See the option -blocksize of command transfer::copy::do in
118 the package transfer::copy.
119 OPTIONS
121 All data sources support the options listed below. It should be noted
122 that the first four options are semi-exclusive, each specifying a dif‐
123 ferent type of data source and associated content. If these options are
124 specified more than once then the last option specified is used to
125 actually configure the object.
126 -string text
128 This option specifies that the source of the data is an immedi‐
129 ate string, and its associated argument contains the string in
130 question.
131 -channel handle
133 This option specifies that the source of the data is a channel,
134 and its associated argument is the handle of the channel con‐
135 taining the data.
136 -file path
138 This option specifies that the source of the data is a file, and
139 its associated argument is the path of the file containing the
140 data.
141 -variable varname
143 This option specifies that the source of the data is a string
144 stored in a variable, and its associated argument contains the
145 name of the variable in question. The variable is assumed to be
146 global or namespaced, anchored at the global namespace.
147 -size int
149 This option specifies the size of the data transfer. It is
150 optional and defaults to -1. This value, and any other value
151 less than zero signals to transfer all the data from the source.
152 -progress command
154 This option, if specified, defines a command to be invoked for
155 each chunk of bytes transmitted, allowing the user to monitor
156 the progress of the transmission of the data. The callback is
157 always invoked with one additional argument, the number of bytes
158 transmitted so far.
159
161 This document, and the package it describes, will undoubtedly contain
162 bugs and other problems. Please report such in the category transfer
163 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
164 also report any ideas for enhancements you may have for either package
165 and/or documentation.
166 When proposing code changes, please provide unified diffs, i.e the out‐
168 put of diff -u.
169 Note further that attachments are strongly preferred over inlined
171 patches. Attachments can be made by going to the Edit form of the
172 ticket immediately after its creation, and then using the left-most
173 button in the secondary navigation bar.
174
176 channel, copy, data source, transfer
177
179 Transfer module
180
182 Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
183tcllib 0.2 transfer::data::source(n)