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

NAME

8       transfer::receiver - Data source
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       package require transfer::connect  ?0.2?
18
19       package require transfer::receiver  ?0.2?
20
21       transfer::receiver object ?options...?
22
23       transfer::receiver stream channel chan host port ?arg...?
24
25       transfer::receiver stream file path host port ?arg...?
26
27       objectName method ?arg arg ...?
28
29       objectName destroy
30
31       objectName start
32
33       objectName busy
34
35______________________________________________________________________________
36

DESCRIPTION

38       This package pulls data destinations and connection setup together into
39       a combined object for the reception of information  coming  in  over  a
40       socket.   These objects understand all the options from objects created
41       by the packages transfer::data::destination and transfer::connect.
42

API

44   PACKAGE COMMANDS
45       transfer::receiver object ?options...?
46              This command creates a new receiver object  with  an  associated
47              Tcl  command  whose  name is objectName.  This object command is
48              explained in full detail in  the  sections  Object  command  and
49              Object  methods.  The  set  of supported options is explained in
50              section Options.
51
52              The object command will be created under the  current  namespace
53              if  the  objectName is not fully qualified, and in the specified
54              namespace otherwise.  The fully qualified  name  of  the  object
55              command is returned as the result of the command.
56
57       transfer::receiver stream channel chan host port ?arg...?
58              This method creates a fire-and-forget transfer for the data com‐
59              ing from the source at host/port (details below) and writing  to
60              the  channel  chan,  starting  at the current seek location. The
61              channel is configured to use binary translation and encoding for
62              the  transfer.   The channel is not closed when the transfer has
63              completed. This is left to the completion callback.
64
65              If both host and port are provided an active connection  to  the
66              data  source is made. If only a port is specified (with host the
67              empty string) then a passive connection is  made  instead,  i.e.
68              the receiver then waits for a conneciton by the transmitter.
69
70              Any arguments after the port are treated as options and are used
71              to configure the internal  receiver  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 receiver object.  This callback is only given
76              the  number  of bytes and transfered, and possibly an error mes‐
77              sage. No reference to the internally  used  receiver  object  is
78              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              receiver  object  is listening on otherwise, i.e when it is con‐
83              figured 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::receiver stream file path host port ?arg...?
88              This method is like stream channel,  except  that  the  received
89              data is written to the file path, replacing any prior content.
90
91   OBJECT COMMAND
92       All  objects  created by the ::transfer::receiver command have the fol‐
93       lowing 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  reception  is
103              on  progress will cause errors later on, when the reception com‐
104              pletes and tries to access the now missing  data  structures  of
105              the destroyed object.
106
107       objectName start
108              This method initiates the data reception, setting up the connec‐
109              tion first and then copying the received  information  into  the
110              destination.   The  method will throw an error if a reception is
111              already/still in progress.  I.e. it is not possible to  run  two
112              receptions  in  parallel, only in sequence.  Errors will also be
113              thrown if the configuration of the data destination is  invalid,
114              or if no completion callback was specified.
115
116              The  result  returned  by  the method is the empty string for an
117              object configured to make an active connection, and the port the
118              object  is  listening on otherwise, i.e when it is configured to
119              connect passively.  See also the package  transfer::connect  and
120              the  description  of the method connect for where this behaviour
121              comes from.
122
123       objectName busy
124              This method returns a boolean value telling us whether a  recep‐
125              tion is in progress (True), or not (False).
126
127   OPTIONS
128       All  receiver  objects  support  the  union of the options supported by
129       their connect and data destination components, plus one of  their  own.
130       See also the documentation for the packages transfer::data::destination
131       and transfer::connect.
132
133       -command cmdprefix
134              This option specifies the command to invoke when  the  reception
135              of  the  information has been completed.  The arguments given to
136              this command are the same as given to the completion callback of
137              the  command  transfer::copy::do  provided by the package trans‐
138              fer::copy.
139
140       -mode mode
141              This option specifies the mode the object is in. It is  optional
142              and defaults to active mode. The two possible modes are:
143
144              active In this mode the two options -host and -port are relevant
145                     and specify the host and TCP port the object has to  con‐
146                     nect to. The host is given by either name or IP address.
147
148              passive
149                     In  this  mode  the  option -host has no relevance and is
150                     ignored should it be configured.   The  only  option  the
151                     object  needs  is -port, and it specifies the TCP port on
152                     which the listening socket is opened to await the connec‐
153                     tion from the partner.
154
155       -host hostname-or-ipaddr
156              This  option  specifies  the  host to connect to in active mode,
157              either by name or ip-address. An object configured  for  passive
158              mode ignores this option.
159
160       -port int
161              For  active  mode  this  option specifies the port the object is
162              expected to connect to. For passive mode however it is the  port
163              where the object creates the listening socket waiting for a con‐
164              nection. It defaults to 0, which allows the  OS  to  choose  the
165              actual port to listen on.
166
167       -socketcmd command
168              This  option  allows the user to specify which command to use to
169              open a socket. The default is to use the builtin  ::socket.  Any
170              compatible with that command is allowed.
171
172              The envisioned main use is the specfication of tls::socket. I.e.
173              this option allows the creation  of  secure  transfer  channels,
174              without  making  this  package  explicitly  dependent on the tls
175              package.
176
177              See also section Secure connections.
178
179       -encoding encodingname
180
181       -eofchar eofspec
182
183       -translation transspec
184              These options are the same as are recognized by the builtin com‐
185              mand  fconfigure.  They  provide the configuration to be set for
186              the channel between the two partners after it  has  been  estab‐
187              lished, but before the callback is invoked (See method connect).
188
189       -channel handle
190              This  option  specifies  that  the  destination of the data is a
191              channel, and its associated argument is the handle of the  chan‐
192              nel to write the received data to.
193
194       -file path
195              This  option  specifies  that  the  destination of the data is a
196              file, and its associated argument is the path  of  the  file  to
197              write the received data to.
198
199       -variable varname
200              This  option  specifies  that  the  destination of the data is a
201              variable, and its associated argument contains the name  of  the
202              variable  to write the received data to. The variable is assumed
203              to be global or namespaced, anchored at the global namespace.
204
205       -progress command
206              This option, if specified, defines a command to be  invoked  for
207              each  chunk  of bytes received, allowing the user to monitor the
208              progress of the reception of the data. The  callback  is  always
209              invoked  with  one  additional  argument,  the  number  of bytes
210              received so far.
211

SECURE CONNECTIONS

213       One way to secure connections made by objects of  this  package  is  to
214       require  the  package  tls  and then configure the option -socketcmd to
215       force the use of command tls::socket to open the socket.
216
217
218                  # Load and initialize tls
219                  package require tls
220                  tls::init -cafile /path/to/ca/cert -keyfile ...
221
222                  # Create a connector with secure socket setup,
223                  transfer::receiver R -socketcmd tls::socket ...
224                  ...
225
226

TLS SECURITY CONSIDERATIONS

228       This package uses the TLS package to handle the security for https urls
229       and other socket connections.
230
231       Policy  decisions like the set of protocols to support and what ciphers
232       to use are not the responsibility of TLS, nor of  this  package  itself
233       however.   Such  decisions are the responsibility of whichever applica‐
234       tion is using the package, and are likely  influenced  by  the  set  of
235       servers the application will talk to as well.
236
237       For  example,  in light of the recent POODLE attack [http://googleonli
238       nesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
239       ssl-30.html] discovered by Google many servers will disable support for
240       the SSLv3 protocol.  To handle this change the applications  using  TLS
241       must  be  patched,  and not this package, nor TLS itself.  Such a patch
242       may be as simple as generally activating tls1 support, as shown in  the
243       example below.
244
245
246                  package require tls
247                  tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
248
249                  ... your own application code ...
250
251

BUGS, IDEAS, FEEDBACK

253       This  document,  and the package it describes, will undoubtedly contain
254       bugs and other problems.  Please report such in the  category  transfer
255       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
256       also report any ideas for enhancements you may have for either  package
257       and/or documentation.
258
259       When proposing code changes, please provide unified diffs, i.e the out‐
260       put of diff -u.
261
262       Note further that  attachments  are  strongly  preferred  over  inlined
263       patches.  Attachments  can  be  made  by  going to the Edit form of the
264       ticket immediately after its creation, and  then  using  the  left-most
265       button in the secondary navigation bar.
266

KEYWORDS

268       channel, copy, data destination, receiver, secure, ssl, tls, transfer
269

CATEGORY

271       Transfer module
272
274       Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>
275
276
277
278
279tcllib                                0.2                transfer::receiver(n)
Impressum