NAME
TclCurl: - get a URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP,
TELNET, DICT, FILE or LDAP syntax.
SYNOPSIS
curl::multiinit
multiHandle addhandle
multiHandle removehandle
multiHandle configure
multiHandle perform
multiHandle active
multiHandle getinfo
multihandle cleanup
multihandle auto
curl::multistrerror errorCode
DESCRIPTION
TclCurl’s multi interface introduces several new abilities that the
easy interface refuses to offer. They are mainly:
Enable a "pull" interface. The application that uses TclCurl decides
where and when to get/send data.
Enable multiple simultaneous transfers in the same thread without
making it complicated for the application.
Keep Tk GUIs ’alive’ while transfers are taking place.
Blocking
A few areas in the code are still using blocking code, even when used
from the multi interface. While we certainly want and intend for these
to get fixed in the future, you should be aware of the following
current restrictions:
Name resolves on non-windows unless c-ares is used.
GnuTLS SSL connections.
Active FTP connections.
HTTP proxy CONNECT operations.
TFTP transfers
file:// transfers.
curl::multiinit
This procedure must be the first one to call, it returns a multiHandle
that you need to use to invoke TclCurl procedures. The init MUST have a
corresponding call to cleanup when the operation is completed.
RETURN VALUE
multiHandle to use.
multiHandle addhandle ?easyHandle?
Each single transfer is built up with an ’easy’ handle, the kind we
have been using so far with TclCurl, you must create them and setup the
appropriate options for each of them. Then we add them to the ’multi
stack’ using the addhandle command.
If the easy handle is not set to use a shared or global DNS cache, it
will be made to use the DNS cache that is shared between all easy
handles within the multi handle.
When an easy handle has been added to a multi stack, you can not and
you must not use perform on that handle!
multiHandle is the return code from the curl::multiinit call.
RETURN VALUE The possible return values are:
-1 Handle added to the multi stack, please call perform soon
0 Handle added ok.
1 Invalid multi handle.
2 Invalid ’easy’ handle. It could mean that it isn’t an easy
handle at all, or possibly that the handle already is in used by
this or another multi handle.
3 Out of memory, you should never get this.
4 You found a bug in TclCurl.
multiHandle removehandle ?easyHandle?
When a transfer is done or if we want to stop a transfer before it is
completed, we can use the removehandle command. Once removed from the
multi handle, we can again use other easy interface functions on it.
Please note that when a single transfer is completed, the easy handle
is still left added to the multi stack. You need to remove it and then
close or, possibly, set new options to it and add it again to the multi
handle to start another transfer.
RETURN VALUE The possible return values are:
0 Handle removed ok.
1 Invalid multi handle.
2 Invalid ’easy’ handle.
3 Out of memory, you should never get this.
4 You found a bug in TclCurl.
multiHandle configure
So far the only option is:
-pipelining
Pass a 1 to enable or 0 to disable. Enabling pipelining on a
multi handle will make it attempt to perform HTTP Pipelining as
far as possible for transfers using this handle. This means that
if you add a second request that can use an already existing
connection, the second request will be "piped" on the same
connection rather than being executed in parallel.
-maxconnects
Pass a number which will be used as the maximum amount of
simultaneously open connections that TclCurl may cache. Default
is 10, and TclCurl will enlarge the size for each added easy
handle to make it fit 4 times the number of added easy handles.
By setting this option, you can prevent the cache size to grow
beyond the limit set by you. When the cache is full, curl closes
the oldest one in the cache to prevent the number of open
connections to increase.
This option is for the multi handle’s use only, when using the
easy interface you should instead use it’s own maxconnects
option.
multiHandle perform
Adding the easy handles to the multi stack does not start any transfer.
Remember that one of the main ideas with this interface is to let your
application drive. You drive the transfers by invoking perform.
TclCurl will then transfer data if there is anything available to
transfer. It’ll use the callbacks and everything else we have setup in
the individual easy handles. It’ll transfer data on all current
transfers in the multi stack that are ready to transfer anything. It
may be all, it may be none.
When you call perform and the amount of Irunning handles is changed
from the previous call (or is less than the amount of easy handles you
added to the multi handle), you know that there is one or more
transfers less "running". You can then call getinfo to get information
about each individual completed transfer.
RETURN VALUE If everything goes well, it returns the number of running
handles, ’0’ if all are done. In case of error, it will return the
error code.
multiHandle active
In order to know if any of the easy handles are ready to transfer data
before invoking perform you can use the active command, it will return
the number of transfers currently active.
RETURN VALUE The number of active transfers or ’-1’ in case of error.
multiHandle getinfo
This procedure returns very simple information about the transfers, you
can get more detail information using the getinfo command on each of
the easy handles.
RETURN VALUE A list with the following elements:
easyHandle about which the info is about.
state of the transfer, ’1’ if it is done.
exit code of the transfer, ’0’ if there was no error,...
Number of messages still in the info queue.
In case there are no messages in the queue it will return {"" 0 0 0}.
multiHandle cleanup
This procedure must be the last one to call for a multi stack, it is
the opposite of the curl::multiinit procedure and must be called with
the same multiHandle as input as the curl::multiinit call returned.
multiHandle auto ?-command command?
Using this command Tcl’s event loop will take care of periodically
invoking perform for you, before using it, you must have already added
at least one easy handle to the multi handle.
The command option allows you to specify a command to invoke after all
the easy handles have finished their transfers, even though I say it is
an option, the truth is you must use this command to cleanup all the
handles, otherwise the transfered files may not be complete.
This support is still in a very experimental state, it may still change
without warning. Any and all comments are welcome.
You can find a couple of examples at tests/multi.
curl::multistrerror errorCode
This procedure returns a string describing the error code passed in the
argument.
SEE ALSO
tclcurl, curl.