1[comment {-*- tcl -*- doctools manpage}]
2[manpage_begin transfer::transmitter n 0.2]
3[copyright {2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
4[moddesc   {Data transfer facilities}]
5[titledesc {Data source}]
6[category  {Transfer module}]
7[require Tcl                    8.4]
8[require snit                   [opt 1.0]]
9[require transfer::copy         [opt 0.2]]
10[require transfer::data::source [opt 0.2]]
11[require transfer::connect      [opt 0.2]]
12[require transfer::transmitter  [opt 0.2]]
13[description]
14[keywords transfer copy channel {data source} transmitter ssl tls secure]
15[para]
16
17This package pulls data sources and connection setup together into a
18combined object for the transmission of information over a socket.
19
20These objects understand all the options from objects created
21by the packages [package transfer::data::source] and
22[package transfer::connect].
23
24
25[section API]
26[subsection {Package commands}]
27
28[list_begin definitions]
29
30[call [cmd transfer::transmitter] \
31	[arg objectName] \
32	[opt [arg options]...]]
33
34This command creates a new transmitter object with an associated Tcl
35command whose name is [arg objectName].
36
37This [term object] command is explained in full detail in the sections
38[sectref {Object command}] and [sectref {Object methods}]. The set of
39supported [arg options] is explained in section [sectref {Options}].
40
41[para]
42
43The object command will be created under the current namespace if the
44[arg objectName] is not fully qualified, and in the specified
45namespace otherwise.
46
47The fully qualified name of the object command is returned as the
48result of the command.
49
50
51[call [cmd transfer::transmitter] [method {stream channel}] \
52     [arg chan] [arg host] [arg port] [opt [arg arg]...]]
53
54This method creates a fire-and-forget transfer for the data contained
55in the channel [arg chan], starting at the current seek location. The
56channel is configured to use binary translation and encoding for the
57transfer.
58
59The channel is automatically closed when the transfer has completed.
60
61[para]
62
63If both [arg host] and [arg port] are provided an [const active]
64connection to the destination is made. If only a [arg port] is
65specified (with [arg host] the empty string) then a [const passive]
66connection is made instead.
67
68[para]
69
70Any arguments after the port are treated as options and are used to
71configure the internal transmitter object.
72
73See the section [sectref Options] for a list of the supported options
74and their meaning.
75
76[emph Note] however that the signature of the command prefix specified
77for the [option -command] callback differs from the signature for the
78same option of the transmitter object.
79
80This callback is only given the number of bytes and transfered, and
81possibly an error message. No reference to the internally used
82transmitter object is made.
83
84[para]
85[vset RETURNER command]
86[vset OBJECT {if it was set}]
87[vset QUALIFIER {internal transmitter}]
88[include include/connect_result_ref.inc]
89
90
91[call [cmd transfer::transmitter] [method {stream file}] \
92     [arg path] [arg host] [arg port] [opt [arg arg]...]]
93
94This method is like [method {stream channel}], except that the data
95contained in the file [arg path] is transfered.
96
97[list_end]
98
99
100[subsection {Object command}]
101
102All objects created by the [cmd ::transfer::transmitter] command have
103the following general form:
104
105[list_begin definitions]
106
107[call [arg objectName] [method method] [opt [arg "arg arg ..."]]]
108
109The method [method method] and its [arg arg]'uments determine the
110exact behavior of the command.
111
112See section [sectref {Object methods}] for the detailed
113specifications.
114
115[list_end]
116
117
118[subsection {Object methods}]
119
120[list_begin definitions]
121
122[call [arg objectName] [method destroy]]
123
124This method destroys the object. Doing so while a transmission is in
125progress will cause errors later on, when the transmission completes
126and tries to access the now missing data structures of the destroyed
127object.
128
129
130[call [arg objectName] [method start]]
131
132This method initiates the data transmission, setting up the connection
133first and then copying the information.
134
135The method will throw an error if a transmission is already/still in
136progress.
137
138I.e. it is not possible to run two transmissions in parallel on a
139single object, only in sequence. Multiple transmitter objects are
140needed to manage parallel transfers, one per transmission.
141
142Errors will also be thrown if the configuration of the data source is
143invalid, or if no completion callback was specified.
144
145[para]
146[vset RETURNER method]
147[vset OBJECT {for an object configured}]
148[vset QUALIFIER {}]
149[include include/connect_result_ref.inc]
150
151
152[call [arg objectName] [method busy]]
153
154This method returns a boolean value telling us whether a transmission
155is in progress ([const True]), or not ([const False]).
156
157[list_end]
158
159
160[subsection Options]
161
162All transmitter objects support the union of the options supported
163by their connect and data source components, plus two of their own.
164
165See also the documentation for the packages
166[package transfer::data::source] and [package transfer::connect].
167
168[list_begin options]
169[opt_def -blocksize [arg int]]
170
171This option specifies the size of the chunks to be transmitted in one
172block. Usage is optional, its default value is [const 1024].
173
174[vset MODE transmission] [include include/complete.inc]
175
176[include include/connect_options.inc]
177[include include/dsource_options.inc]
178[list_end]
179
180[vset OBJCREATE {transfer::transmitter T}]
181[include include/secure.inc]
182
183[vset CATEGORY transfer]
184[include ../doctools2base/include/feedback.inc]
185[manpage_end]
186