← Back to branch summary

~ubuntu-branches/debian/lenny/tclcurl/lenny

« back to all changes in this revision

Viewing changes to doc/tclcurl_multi.html

  • Committer: Bazaar Package Importer
  • Author(s): Sven Hoexter
  • Date: 2008-02-13 21:21:39 UTC
  • mfrom: (1.3.1 upstream) (4.1.1 gutsy)
  • Revision ID: james.westby@ubuntu.com-20080213212139-rj3683kvvyovvuon
Tags: 7.17.1-1
* New upstream release to support curl 7.17.1 features.
* Following lintian advice for debian-rules-ignores-make-clean-error.
* Moved the Homepage from the Description into the new Homepage field.
* Removed man-quoting patch; got applied upstream.
* Standards-Version: 3.7.3 - no changes required.
* Build depend on tcl-dev instead of tcl8.4-dev.
* Refreshed man-section and correct-linking patch.
* Added LDFLAGS += -Wl,-z,defs -Wl,--as-needed so that I can shorten
  the correct-linking patch to kerberos related libs.
* Switched to use tcltk-depends to depend on the right Tcl version.
* Added Vcs-Svn field to debian/control.
* Reworked debian/rules to make it a bit clearer what happens.
* Adopt the new Tcl/Tk policy and move the lib into /usr/lib/tcltk.
* Added patch reformat-tclcurl3 to prevent confusion of man.
* Updated the copyright file and formated it to make lintian happy.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/tclcurl_multi.html
1
1
<HTML><HEAD><TITLE>Manpage of TclCurl</TITLE>
2
2
</HEAD><BODY>
3
3
<H1>TclCurl</H1>
4
 
Section: TclCurl Multi Interface (3)<BR>Updated: 17 April 2006<BR><HR>
 
4
Section: TclCurl Multi Interface (n)<BR>Updated: 1 November 2007<BR><HR>
5
5
 
6
6
<A NAME="lbAB">&nbsp;</A>
7
7
<H2>NAME</H2>
8
8
 
9
 
TclCurl: - get  a  URL with FTP, TFTP, TELNET, LDAP, DICT, FILE, HTTP or HTTPS syntax.
 
9
TclCurl: - get  a  URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE or LDAP syntax.
10
10
<A NAME="lbAC">&nbsp;</A>
11
11
<H2>SYNOPSIS</H2>
12
12
 
19
19
<I>multiHandle</I><B> removehandle</B>
20
20
 
21
21
<P>
 
22
<I>multiHandle</I><B> configure</B>
 
23
 
 
24
<P>
22
25
<I>multiHandle</I><B> perform</B>
23
26
 
24
27
<P>
49
52
complicated for the application.<br><br>
50
53
<li>Keep Tk GUIs 'alive' while transfers are taking place.<br><br>
51
54
</ul>
 
55
<P>
 
56
</DL>
52
57
<A NAME="lbAE">&nbsp;</A>
 
58
<H2>Blocking</H2>
 
59
 
 
60
A few areas in the code are still using blocking code, even when used from the
 
61
multi interface. While we certainly want and intend for these to get fixed in
 
62
the future, you should be aware of the following current restrictions:
 
63
<ul>
 
64
<li>Name resolves on non-windows unless c-ares is used.</B>
 
65
 
 
66
<li>GnuTLS SSL connections.</B>
 
67
 
 
68
<li>Active FTP connections.</B>
 
69
 
 
70
<li>HTTP proxy CONNECT operations.</B>
 
71
 
 
72
<li>SCP and SFTP connections.</B>
 
73
 
 
74
<li>SFTP transfers.</B>
 
75
 
 
76
<li>TFTP transfers</B>
 
77
 
 
78
<li>file:// transfers.</B>
 
79
</ul>
 
80
 
 
81
<P>
 
82
<A NAME="lbAF">&nbsp;</A>
53
83
<H2>curl::multiinit</H2>
54
84
 
55
85
This procedure must be the first one to call, it returns a <I>multiHandle</I>
63
93
 
64
94
to use.
65
95
<P>
66
 
<A NAME="lbAF">&nbsp;</A>
 
96
<A NAME="lbAG">&nbsp;</A>
67
97
<H2>multiHandle addhandle ?easyHandle?</H2>
68
98
 
69
99
<P>
72
102
options for each of them. Then we add them to the 'multi stack' using the
73
103
<I>addhandle</I> command.
74
104
<P>
 
105
If the easy handle is not set to use a shared or global DNS cache, it will be made
 
106
to use the DNS cache that is shared between all easy handles within the multi handle.
 
107
<P>
 
108
When an easy handle has been added to a multi stack, you can not and you must not use
 
109
<I>perform</I> on that handle!
 
110
<P>
 
111
<P>
75
112
<I>multiHandle</I>
76
113
 
77
114
is the return code from the <I>curl::multiinit</I> call.
90
127
<DT>1<DD>
91
128
Invalid multi handle.
92
129
<DT>2<DD>
93
 
Invalid 'easy' handle.
 
130
Invalid 'easy' handle. It could mean that it isn't an easy handle at all, or possibly that
 
131
the handle already is in used by this or another multi handle. 
94
132
<DT>3<DD>
95
133
Out of memory, you should never get this.
96
134
<DT>4<DD>
97
135
You found a bug in TclCurl.
98
136
<P>
99
137
</DL>
100
 
<A NAME="lbAG">&nbsp;</A>
 
138
<A NAME="lbAH">&nbsp;</A>
101
139
<H2>multiHandle removehandle ?easyHandle?</H2>
102
140
 
103
141
<P>
105
143
we can use the <I>removehandle</I> command. Once removed from the multi handle,
106
144
we can again use other easy interface functions on it.
107
145
<P>
 
146
Please note that when a single transfer is completed, the easy handle is still
 
147
left added to the multi stack. You need to remove it and then close or, possibly,
 
148
set new options to it and add it again to the multi handle to start another transfer.
 
149
<P>
 
150
<P>
108
151
<B>RETURN VALUE</B>
109
152
 
110
153
The possible return values are:
121
164
You found a bug in TclCurl.
122
165
<P>
123
166
</DL>
124
 
<A NAME="lbAH">&nbsp;</A>
 
167
<A NAME="lbAI">&nbsp;</A>
 
168
<H2>multiHandle configure</H2>
 
169
 
 
170
So far the only option is:
 
171
<DL COMPACT>
 
172
<DT><B>-pipelining</B>
 
173
 
 
174
<DD>
 
175
Pass a 1 to enable or 0 to disable. Enabling pipelining on a multi handle will
 
176
make it attempt to perform HTTP Pipelining as far as possible for transfers using
 
177
this handle. This means that if you add a second request that can use an already
 
178
existing connection, the second request will be &quot;piped&quot; on the same connection
 
179
rather than being executed in parallel.
 
180
<DT><B>-maxconnects</B>
 
181
 
 
182
<DD>
 
183
Pass a number which will be used as the maximum amount of simultaneously open
 
184
connections that TclCurl may cache. Default is 10, and TclCurl will enlarge
 
185
the size for each added easy handle to make it fit 4 times the number of added
 
186
easy handles.
 
187
<P>
 
188
By setting this option, you can prevent the cache size to grow beyond the limit
 
189
set by you. When the cache is full, curl closes the oldest one in the cache to
 
190
prevent the number of open connections to increase.
 
191
<P>
 
192
This option is for the multi handle's use only, when using the easy interface you should instead use it's own <B>maxconnects</B> option.
 
193
<P>
 
194
</DL>
 
195
<A NAME="lbAJ">&nbsp;</A>
125
196
<H2>multiHandle perform</H2>
126
197
 
127
198
Adding the easy handles to the multi stack does not start any transfer.
140
211
transfers less &quot;running&quot;. You can then call <I>getinfo</I> to
141
212
get information about each individual completed transfer.
142
213
<P>
143
 
<P>
144
214
<B>RETURN VALUE</B>
145
215
 
146
216
If everything goes well, it returns the number of running handles, '0' if all
147
217
are done. In case of error, it will return the error code.
148
218
<P>
149
 
<A NAME="lbAI">&nbsp;</A>
 
219
<A NAME="lbAK">&nbsp;</A>
150
220
<H2>multiHandle active</H2>
151
221
 
152
222
In order to know if any of the easy handles are ready to transfer data before
162
232
 
163
233
The number of active transfers or '-1' in case of error.
164
234
<P>
165
 
<A NAME="lbAJ">&nbsp;</A>
 
235
<A NAME="lbAL">&nbsp;</A>
166
236
<H2>multiHandle getinfo</H2>
167
237
 
168
238
This procedure returns very simple information about the transfers, you
169
 
can get more detail information using the
170
 
<I>getinfo</I>
171
 
 
 
239
can get more detail information using the <I>getinfo</I>
172
240
command on each of the easy handles.
173
241
<P>
 
242
<P>
174
243
<B>RETURN VALUE</B>
175
244
 
176
245
A list with the following elements:
182
251
<DT>In case there are no messages in the queue it will return {&quot;&quot; 0 0 0}.<DD>
183
252
<P>
184
253
</DL>
185
 
<A NAME="lbAK">&nbsp;</A>
 
254
<A NAME="lbAM">&nbsp;</A>
186
255
<H2>multiHandle cleanup</H2>
187
256
 
188
257
This procedure must be the last one to call for a multi stack, it is the opposite of the
196
265
 
197
266
call returned.
198
267
<P>
199
 
<A NAME="lbAL">&nbsp;</A>
 
268
<A NAME="lbAN">&nbsp;</A>
200
269
<H2>multiHandle auto ?-command <I>command</I>?</H2>
201
270
 
202
271
Using this command Tcl's event loop will take care of periodically invoking <B>perform</B>
213
282
<P>
214
283
You can find a couple of examples at <B>tests/multi</B>.
215
284
<P>
216
 
<A NAME="lbAM">&nbsp;</A>
 
285
<A NAME="lbAO">&nbsp;</A>
217
286
<H2>curl::multistrerror errorCode</H2>
218
287
 
219
288
This procedure returns a string describing the error code passed in the argument.
220
289
<P>
221
 
<A NAME="lbAN">&nbsp;</A>
 
290
<A NAME="lbAP">&nbsp;</A>
222
291
<H2>SEE ALSO</H2>
223
292
 
224
293
<I>tclcurl, curl.</I>
231
300
<DT><A HREF="#lbAB">NAME</A><DD>
232
301
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
233
302
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
234
 
<DT><A HREF="#lbAE">curl::multiinit</A><DD>
235
 
<DT><A HREF="#lbAF">multiHandle addhandle ?easyHandle?</A><DD>
236
 
<DT><A HREF="#lbAG">multiHandle removehandle ?easyHandle?</A><DD>
237
 
<DT><A HREF="#lbAH">multiHandle perform</A><DD>
238
 
<DT><A HREF="#lbAI">multiHandle active</A><DD>
239
 
<DT><A HREF="#lbAJ">multiHandle getinfo</A><DD>
240
 
<DT><A HREF="#lbAK">multiHandle cleanup</A><DD>
241
 
<DT><A HREF="#lbAL">multiHandle auto ?-command <I>command</I>?</A><DD>
242
 
<DT><A HREF="#lbAM">curl::multistrerror errorCode</A><DD>
243
 
<DT><A HREF="#lbAN">SEE ALSO</A><DD>
 
303
<DT><A HREF="#lbAE">Blocking</A><DD>
 
304
<DT><A HREF="#lbAF">curl::multiinit</A><DD>
 
305
<DT><A HREF="#lbAG">multiHandle addhandle ?easyHandle?</A><DD>
 
306
<DT><A HREF="#lbAH">multiHandle removehandle ?easyHandle?</A><DD>
 
307
<DT><A HREF="#lbAI">multiHandle configure</A><DD>
 
308
<DT><A HREF="#lbAJ">multiHandle perform</A><DD>
 
309
<DT><A HREF="#lbAK">multiHandle active</A><DD>
 
310
<DT><A HREF="#lbAL">multiHandle getinfo</A><DD>
 
311
<DT><A HREF="#lbAM">multiHandle cleanup</A><DD>
 
312
<DT><A HREF="#lbAN">multiHandle auto ?-command <I>command</I>?</A><DD>
 
313
<DT><A HREF="#lbAO">curl::multistrerror errorCode</A><DD>
 
314
<DT><A HREF="#lbAP">SEE ALSO</A><DD>
244
315
</DL>
245
316
<HR>
246
317
This document was created by man2html, using the manual pages.<BR>