1transfer::transmitter(n)   Data transfer facilities   transfer::transmitter(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       transfer::transmitter - Data source
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require snit  ?1.0?
14
15       package require transfer::copy  ?0.2?
16
17       package require transfer::data::source  ?0.2?
18
19       package require transfer::connect  ?0.2?
20
21       package require transfer::transmitter  ?0.2?
22
23       transfer::transmitter objectName ?options...?
24
25       transfer::transmitter stream channel chan host port ?arg...?
26
27       transfer::transmitter stream file path host port ?arg...?
28
29       objectName method ?arg arg ...?
30
31       objectName destroy
32
33       objectName start
34
35       objectName busy
36
37______________________________________________________________________________
38

DESCRIPTION

40       This  package  pulls  data sources and connection setup together into a
41       combined object for the transmission  of  information  over  a  socket.
42       These  objects  understand  all the options from objects created by the
43       packages transfer::data::source and transfer::connect.
44

API

46   PACKAGE COMMANDS
47       transfer::transmitter objectName ?options...?
48              This command creates a new transmitter object with an associated
49              Tcl  command  whose  name is objectName.  This object command is
50              explained in full detail in the sections Object command and  Ob‐
51              ject  methods. The set of supported options is explained in sec‐
52              tion Options.
53
54              The object command will be created under the  current  namespace
55              if  the  objectName is not fully qualified, and in the specified
56              namespace otherwise.  The fully qualified  name  of  the  object
57              command is returned as the result of the command.
58
59       transfer::transmitter stream channel chan host port ?arg...?
60              This method creates a fire-and-forget transfer for the data con‐
61              tained in the channel chan, starting at the current  seek  loca‐
62              tion.  The  channel  is configured to use binary translation and
63              encoding for the transfer.  The channel is automatically  closed
64              when the transfer has completed.
65
66              If  both  host and port are provided an active connection to the
67              destination is made. If only a port is specified (with host  the
68              empty string) then a passive connection is made instead.
69
70              Any arguments after the port are treated as options and are used
71              to configure the internal transmitter object.  See  the  section
72              Options  for  a list of the supported options and their meaning.
73              Note however that the signature of the command prefix  specified
74              for  the  -command  callback  differs from the signature for the
75              same option of the transmitter object.  This  callback  is  only
76              given  the number of bytes and transfered, and possibly an error
77              message. No reference to the internally used transmitter  object
78              is made.
79
80              The result returned by the command is the empty string if it was
81              set to make an active connection,  and  the  port  the  internal
82              transmitter  object  is  listening  on otherwise, i.e when it is
83              configured to connect passively.  See also  the  package  trans‐
84              fer::connect and the description of the method connect for where
85              this behaviour comes from.
86
87       transfer::transmitter stream file path host port ?arg...?
88              This method is like stream channel, except that  the  data  con‐
89              tained in the file path is transfered.
90
91   OBJECT COMMAND
92       All  objects  created  by  the ::transfer::transmitter command have the
93       following general form:
94
95       objectName method ?arg arg ...?
96              The method method and its arg'uments determine the exact  behav‐
97              ior of the command.  See section Object methods for the detailed
98              specifications.
99
100   OBJECT METHODS
101       objectName destroy
102              This method destroys the object. Doing so while  a  transmission
103              is in progress will cause errors later on, when the transmission
104              completes and tries to access the now missing data structures of
105              the destroyed object.
106
107       objectName start
108              This method initiates the data transmission, setting up the con‐
109              nection first and then copying the information.  The method will
110              throw  an  error if a transmission is already/still in progress.
111              I.e. it is not possible to run two transmissions in parallel  on
112              a  single object, only in sequence. Multiple transmitter objects
113              are needed to manage parallel transfers, one  per  transmission.
114              Errors  will  also  be  thrown  if the configuration of the data
115              source is invalid, or if no completion callback was specified.
116
117              The result returned by the method is the empty string for an ob‐
118              ject  configured  to make an active connection, and the port the
119              object is listening on otherwise, i.e when it is  configured  to
120              connect  passively.   See also the package transfer::connect and
121              the description of the method connect for where  this  behaviour
122              comes from.
123
124       objectName busy
125              This  method returns a boolean value telling us whether a trans‐
126              mission is in progress (True), or not (False).
127
128   OPTIONS
129       All transmitter objects support the union of the options  supported  by
130       their  connect  and data source components, plus two of their own.  See
131       also the documentation  for  the  packages  transfer::data::source  and
132       transfer::connect.
133
134       -blocksize int
135              This  option  specifies the size of the chunks to be transmitted
136              in one block. Usage is optional, its default value is 1024.
137
138       -command cmdprefix
139              This option specifies the command to invoke when  the  transmis‐
140              sion of the information has been completed.  The arguments given
141              to this command are the same as given to the completion callback
142              of the command transfer::copy::do provided by the package trans‐
143              fer::copy.
144
145       -mode mode
146              This option specifies the mode the object is in. It is  optional
147              and defaults to active mode. The two possible modes are:
148
149              active In this mode the two options -host and -port are relevant
150                     and specify the host and TCP port the object has to  con‐
151                     nect to. The host is given by either name or IP address.
152
153              passive
154                     In this mode the option -host has no relevance and is ig‐
155                     nored should it be configured.  The only option  the  ob‐
156                     ject  needs  is  -port,  and it specifies the TCP port on
157                     which the listening socket is opened to await the connec‐
158                     tion from the partner.
159
160       -host hostname-or-ipaddr
161              This option specifies the host to connect to in active mode, ei‐
162              ther by name or ip-address. An  object  configured  for  passive
163              mode ignores this option.
164
165       -port int
166              For active mode this option specifies the port the object is ex‐
167              pected to connect to. For passive mode however it  is  the  port
168              where the object creates the listening socket waiting for a con‐
169              nection. It defaults to 0, which allows the OS to choose the ac‐
170              tual port to listen on.
171
172       -socketcmd command
173              This  option  allows the user to specify which command to use to
174              open a socket. The default is to use the builtin  ::socket.  Any
175              compatible with that command is allowed.
176
177              The envisioned main use is the specfication of tls::socket. I.e.
178              this option allows the creation  of  secure  transfer  channels,
179              without  making  this  package  explicitly  dependent on the tls
180              package.
181
182              See also section Secure connections.
183
184       -encoding encodingname
185
186       -eofchar eofspec
187
188       -translation transspec
189              These options are the same as are recognized by the builtin com‐
190              mand  fconfigure.  They  provide the configuration to be set for
191              the channel between the two partners after it  has  been  estab‐
192              lished, but before the callback is invoked (See method connect).
193
194       -string text
195              This  option specifies that the source of the data is an immedi‐
196              ate string, and its associated argument contains the  string  in
197              question.
198
199       -channel handle
200              This  option specifies that the source of the data is a channel,
201              and its associated argument is the handle of  the  channel  con‐
202              taining the data.
203
204       -file path
205              This option specifies that the source of the data is a file, and
206              its associated argument is the path of the file  containing  the
207              data.
208
209       -variable varname
210              This  option  specifies  that the source of the data is a string
211              stored in a variable, and its associated argument  contains  the
212              name  of the variable in question. The variable is assumed to be
213              global or namespaced, anchored at the global namespace.
214
215       -size int
216              This option specifies the size of the data transfer. It  is  op‐
217              tional  and defaults to -1. This value, and any other value less
218              than zero signals to transfer all the data from the source.
219
220       -progress command
221              This option, if specified, defines a command to be  invoked  for
222              each  chunk  of  bytes transmitted, allowing the user to monitor
223              the progress of the transmission of the data.  The  callback  is
224              always invoked with one additional argument, the number of bytes
225              transmitted so far.
226

SECURE CONNECTIONS

228       One way to secure connections made by objects of this package is to re‐
229       quire the package tls and then configure the option -socketcmd to force
230       the use of command tls::socket to open the socket.
231
232
233                  # Load and initialize tls
234                  package require tls
235                  tls::init -cafile /path/to/ca/cert -keyfile ...
236
237                  # Create a connector with secure socket setup,
238                  transfer::transmitter T -socketcmd tls::socket ...
239                  ...
240
241

TLS SECURITY CONSIDERATIONS

243       This package uses the TLS package to handle the security for https urls
244       and other socket connections.
245
246       Policy  decisions like the set of protocols to support and what ciphers
247       to use are not the responsibility of TLS, nor of  this  package  itself
248       however.   Such  decisions are the responsibility of whichever applica‐
249       tion is using the package, and are likely  influenced  by  the  set  of
250       servers the application will talk to as well.
251
252       For  example,  in light of the recent POODLE attack [http://googleonli
253       nesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
254       ssl-30.html] discovered by Google many servers will disable support for
255       the SSLv3 protocol.  To handle this change the applications  using  TLS
256       must  be  patched,  and not this package, nor TLS itself.  Such a patch
257       may be as simple as generally activating tls1 support, as shown in  the
258       example below.
259
260
261                  package require tls
262                  tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
263
264                  ... your own application code ...
265
266

BUGS, IDEAS, FEEDBACK

268       This  document,  and the package it describes, will undoubtedly contain
269       bugs and other problems.  Please report such in the  category  transfer
270       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
271       also report any ideas for enhancements you may have for either  package
272       and/or documentation.
273
274       When proposing code changes, please provide unified diffs, i.e the out‐
275       put of diff -u.
276
277       Note further that  attachments  are  strongly  preferred  over  inlined
278       patches.  Attachments  can  be  made  by  going to the Edit form of the
279       ticket immediately after its creation, and  then  using  the  left-most
280       button in the secondary navigation bar.
281

KEYWORDS

283       channel, copy, data source, secure, ssl, tls, transfer, transmitter
284

CATEGORY

286       Transfer module
287
289       Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
290
291
292
293
294tcllib                                0.2             transfer::transmitter(n)
Impressum