1
.\" You can view this file with:
3
.\" Adapted from libcurl docs by fandom@telefonica.net
4
.TH TclCurl n "8 September 2008" "TclCurl 7.19.0" "TclCurl Multi Interface"
6
TclCurl: - get a URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE or LDAP syntax.
10
.IB multiHandle " addhandle"
12
.IB multiHandle " removehandle"
14
.IB multiHandle " configure"
16
.IB multiHandle " perform"
18
.IB multiHandle " active"
20
.IB multiHandle " getinfo "
22
.IB multihandle " cleanup"
24
.IB multihandle " auto"
26
.BI "curl::multistrerror " errorCode
29
TclCurl's multi interface introduces several new abilities that the easy
30
interface refuses to offer. They are mainly:
32
Enable a "pull" interface. The application that uses TclCurl decides where and when to get/send data.
34
Enable multiple simultaneous transfers in the same thread without making it complicated for the application.
36
Keep Tk GUIs 'alive' while transfers are taking place.
39
A few areas in the code are still using blocking code, even when used from the
40
multi interface. While we certainly want and intend for these to get fixed in
41
the future, you should be aware of the following current restrictions:
44
.B Name resolves on non-windows unless c-ares is used.
46
.B GnuTLS SSL connections.
48
.B Active FTP connections.
50
.B HTTP proxy CONNECT operations.
58
This procedure must be the first one to call, it returns a \fImultiHandle\fP
59
that you need to use to invoke TclCurl procedures. The init MUST have a
60
corresponding call to \fIcleanup\fP when the operation is completed.
67
.SH multiHandle addhandle ?easyHandle?
69
Each single transfer is built up with an 'easy' handle, the kind we have been
70
using so far with TclCurl, you must create them and setup the appropriate
71
options for each of them. Then we add them to the 'multi stack' using the
72
\fIaddhandle\fP command.
74
If the easy handle is not set to use a shared or global DNS cache, it will be made
75
to use the DNS cache that is shared between all easy handles within the multi handle.
77
When an easy handle has been added to a multi stack, you can not and you must not use
78
\fIperform\fP on that handle!
82
is the return code from the \fIcurl::multiinit\fP call.
85
The possible return values are:
87
Handle added to the multi stack, please call
95
Invalid 'easy' handle. It could mean that it isn't an easy handle at all, or possibly that
96
the handle already is in used by this or another multi handle.
98
Out of memory, you should never get this.
100
You found a bug in TclCurl.
102
.SH multiHandle removehandle ?easyHandle?
104
When a transfer is done or if we want to stop a transfer before it is completed,
105
we can use the \fIremovehandle\fP command. Once removed from the multi handle,
106
we can again use other easy interface functions on it.
108
Please note that when a single transfer is completed, the easy handle is still
109
left added to the multi stack. You need to remove it and then close or, possibly,
110
set new options to it and add it again to the multi handle to start another transfer.
114
The possible return values are:
118
Invalid multi handle.
120
Invalid 'easy' handle.
122
Out of memory, you should never get this.
124
You found a bug in TclCurl.
126
.SH multiHandle configure
127
So far the only option is:
130
Pass a 1 to enable or 0 to disable. Enabling pipelining on a multi handle will
131
make it attempt to perform HTTP Pipelining as far as possible for transfers using
132
this handle. This means that if you add a second request that can use an already
133
existing connection, the second request will be "piped" on the same connection
134
rather than being executed in parallel.
137
Pass a number which will be used as the maximum amount of simultaneously open
138
connections that TclCurl may cache. Default is 10, and TclCurl will enlarge
139
the size for each added easy handle to make it fit 4 times the number of added
142
By setting this option, you can prevent the cache size to grow beyond the limit
143
set by you. When the cache is full, curl closes the oldest one in the cache to
144
prevent the number of open connections to increase.
146
This option is for the multi handle's use only, when using the easy interface you should instead use it's own \fBmaxconnects\fP option.
148
.SH multiHandle perform
149
Adding the easy handles to the multi stack does not start any transfer.
150
Remember that one of the main ideas with this interface is to let your
151
application drive. You drive the transfers by invoking
153
TclCurl will then transfer data if there is anything available to transfer.
154
It'll use the callbacks and everything else we have setup in the individual
155
easy handles. It'll transfer data on all current transfers in the multi stack
156
that are ready to transfer anything. It may be all, it may be none.
158
When you call \fBperform\fP and the amount of Irunning handles is
159
changed from the previous call (or is less than the amount of easy handles
160
you added to the multi handle), you know that there is one or more
161
transfers less "running". You can then call \fIgetinfo\fP to
162
get information about each individual completed transfer.
165
If everything goes well, it returns the number of running handles, '0' if all
166
are done. In case of error, it will return the error code.
168
.SH multiHandle active
169
In order to know if any of the easy handles are ready to transfer data before
174
command, it will return the number of transfers currently active.
177
The number of active transfers or '-1' in case of error.
179
.SH multiHandle getinfo
180
This procedure returns very simple information about the transfers, you
181
can get more detail information using the \fIgetinfo\fP
182
command on each of the easy handles.
186
A list with the following elements:
188
easyHandle about which the info is about.
190
state of the transfer, '1' if it is done.
192
exit code of the transfer, '0' if there was no error,...
194
Number of messages still in the info queue.
196
In case there are no messages in the queue it will return {"" 0 0 0}.
198
.SH multiHandle cleanup
199
This procedure must be the last one to call for a multi stack, it is the opposite of the
201
procedure and must be called with the same
207
.SH multiHandle auto ?-command \fIcommand\fP?
208
Using this command Tcl's event loop will take care of periodically invoking \fBperform\fP
209
for you, before using it, you must have already added at least one easy handle to
212
The \fBcommand\fP option allows you to specify a command to invoke after all the easy
213
handles have finished their transfers, even though I say it is an option, the truth is
214
you must use this command to cleanup all the handles, otherwise the transfered files
217
This support is still in a very experimental state, it may still change without warning.
218
Any and all comments are welcome.
220
You can find a couple of examples at \fBtests/multi\fP.
222
.SH curl::multistrerror errorCode
223
This procedure returns a string describing the error code passed in the argument.
added
removed
doc/SinComprimir/tclcurl_multi.n
