321 lines
9.3 KiB
HTML
Executable File
321 lines
9.3 KiB
HTML
Executable File
<HTML><HEAD><TITLE>Manpage of TclCurl</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>TclCurl</H1>
|
|
Section: TclCurl Multi Interface (3)<BR>Updated: 03 September 2011<BR><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
TclCurl: - get a URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE, LDAP,
|
|
LDAPS, IMAP, IMAPS, POP, POP3, SMTP, SMTPS and gopher syntax.
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>curl::multiinit</B>
|
|
|
|
<P>
|
|
<I>multiHandle</I><B> addhandle</B>
|
|
|
|
<P>
|
|
<I>multiHandle</I><B> removehandle</B>
|
|
|
|
<P>
|
|
<I>multiHandle</I><B> configure</B>
|
|
|
|
<P>
|
|
<I>multiHandle</I><B> perform</B>
|
|
|
|
<P>
|
|
<I>multiHandle</I><B> active</B>
|
|
|
|
<P>
|
|
<I>multiHandle</I><B> getinfo </B>
|
|
|
|
<P>
|
|
<I>multihandle</I><B> cleanup</B>
|
|
|
|
<P>
|
|
<I>multihandle</I><B> auto</B>
|
|
|
|
<P>
|
|
<B>curl::multistrerror </B><I>errorCode</I>
|
|
|
|
<P>
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
TclCurl's multi interface introduces several new abilities that the easy
|
|
interface refuses to offer. They are mainly:
|
|
<ul>
|
|
<li>Enable a "pull" interface. The application that uses TclCurl decides where
|
|
and when to get/send data.<br><br>
|
|
<li>Enable multiple simultaneous transfers in the same thread without making it
|
|
complicated for the application.<br><br>
|
|
<li>Keep Tk GUIs 'alive' while transfers are taking place.<br><br>
|
|
</ul>
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>Blocking</H2>
|
|
|
|
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:
|
|
<ul>
|
|
<li>Name resolves on non-windows unless c-ares is used.</B>
|
|
|
|
<li>GnuTLS SSL connections.</B>
|
|
|
|
<li>Active FTP connections.</B>
|
|
|
|
<li>HTTP proxy CONNECT operations.</B>
|
|
|
|
<li>SCP and SFTP connections.</B>
|
|
|
|
<li>SFTP transfers.</B>
|
|
|
|
<li>TFTP transfers</B>
|
|
|
|
<li>file:// transfers.</B>
|
|
</ul>
|
|
|
|
<P>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>curl::multiinit</H2>
|
|
|
|
This procedure must be the first one to call, it returns a <I>multiHandle</I>
|
|
that you need to use to invoke TclCurl procedures. The init MUST have a
|
|
corresponding call to <I>cleanup</I> when the operation is completed.
|
|
<P>
|
|
<B>RETURN VALUE</B>
|
|
|
|
<P>
|
|
<I>multiHandle</I>
|
|
|
|
to use.
|
|
<P>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>multiHandle addhandle ?easyHandle?</H2>
|
|
|
|
<P>
|
|
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
|
|
<I>addhandle</I> command.
|
|
<P>
|
|
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.
|
|
<P>
|
|
When an easy handle has been added to a multi stack, you can not and you must not use
|
|
<I>perform</I> on that handle!
|
|
<P>
|
|
<P>
|
|
<I>multiHandle</I>
|
|
|
|
is the return code from the <I>curl::multiinit</I> call.
|
|
<P>
|
|
<B>RETURN VALUE</B>
|
|
|
|
The possible return values are:
|
|
<DL COMPACT>
|
|
<DT>-1<DD>
|
|
Handle added to the multi stack, please call
|
|
<I>perform</I>
|
|
|
|
soon
|
|
<DT>0<DD>
|
|
Handle added ok.
|
|
<DT>1<DD>
|
|
Invalid multi handle.
|
|
<DT>2<DD>
|
|
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.
|
|
<DT>3<DD>
|
|
Out of memory, you should never get this.
|
|
<DT>4<DD>
|
|
You found a bug in TclCurl.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>multiHandle removehandle ?easyHandle?</H2>
|
|
|
|
<P>
|
|
When a transfer is done or if we want to stop a transfer before it is completed,
|
|
we can use the <I>removehandle</I> command. Once removed from the multi handle,
|
|
we can again use other easy interface functions on it.
|
|
<P>
|
|
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.
|
|
<P>
|
|
<P>
|
|
<B>RETURN VALUE</B>
|
|
|
|
The possible return values are:
|
|
<DL COMPACT>
|
|
<DT>0<DD>
|
|
Handle removed ok.
|
|
<DT>1<DD>
|
|
Invalid multi handle.
|
|
<DT>2<DD>
|
|
Invalid 'easy' handle.
|
|
<DT>3<DD>
|
|
Out of memory, you should never get this.
|
|
<DT>4<DD>
|
|
You found a bug in TclCurl.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>multiHandle configure</H2>
|
|
|
|
So far the only option is:
|
|
<DL COMPACT>
|
|
<DT><B>-pipelining</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT><B>-maxconnects</B>
|
|
|
|
<DD>
|
|
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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>multiHandle perform</H2>
|
|
|
|
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
|
|
<I>perform.</I>
|
|
|
|
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.
|
|
<P>
|
|
When you call <B>perform</B> 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 <I>getinfo</I> to
|
|
get information about each individual completed transfer.
|
|
<P>
|
|
<B>RETURN VALUE</B>
|
|
|
|
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.
|
|
<P>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>multiHandle active</H2>
|
|
|
|
In order to know if any of the easy handles are ready to transfer data before
|
|
invoking
|
|
<I>perform</I>
|
|
|
|
you can use the
|
|
<I>active</I>
|
|
|
|
command, it will return the number of transfers currently active.
|
|
<P>
|
|
<B>RETURN VALUE</B>
|
|
|
|
The number of active transfers or '-1' in case of error.
|
|
<P>
|
|
<A NAME="lbAL"> </A>
|
|
<H2>multiHandle getinfo</H2>
|
|
|
|
This procedure returns very simple information about the transfers, you
|
|
can get more detail information using the <I>getinfo</I>
|
|
command on each of the easy handles.
|
|
<P>
|
|
<P>
|
|
<B>RETURN VALUE</B>
|
|
|
|
A list with the following elements:
|
|
<DL COMPACT>
|
|
<DT>easyHandle about which the info is about.<DD>
|
|
<DT>state of the transfer, '1' if it is done.<DD>
|
|
<DT>exit code of the transfer, '0' if there was no error,...<DD>
|
|
<DT>Number of messages still in the info queue.<DD>
|
|
<DT>In case there are no messages in the queue it will return {"" 0 0 0}.<DD>
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAM"> </A>
|
|
<H2>multiHandle cleanup</H2>
|
|
|
|
This procedure must be the last one to call for a multi stack, it is the opposite of the
|
|
<I>curl::multiinit</I>
|
|
|
|
procedure and must be called with the same
|
|
<I>multiHandle</I>
|
|
|
|
as input as the
|
|
<B>curl::multiinit</B>
|
|
|
|
call returned.
|
|
<P>
|
|
<A NAME="lbAN"> </A>
|
|
<H2>multiHandle auto ?-command <I>command</I>?</H2>
|
|
|
|
Using this command Tcl's event loop will take care of periodically invoking <B>perform</B>
|
|
for you, before using it, you must have already added at least one easy handle to
|
|
the multi handle.
|
|
<P>
|
|
The <B>command</B> 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.
|
|
<P>
|
|
This support is still in a very experimental state, it may still change without warning.
|
|
Any and all comments are welcome.
|
|
<P>
|
|
You can find a couple of examples at <B>tests/multi</B>.
|
|
<P>
|
|
<A NAME="lbAO"> </A>
|
|
<H2>curl::multistrerror errorCode</H2>
|
|
|
|
This procedure returns a string describing the error code passed in the argument.
|
|
<P>
|
|
<A NAME="lbAP"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<I>tclcurl, curl.</I>
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT><A HREF="#lbAB">NAME</A><DD>
|
|
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT><A HREF="#lbAE">Blocking</A><DD>
|
|
<DT><A HREF="#lbAF">curl::multiinit</A><DD>
|
|
<DT><A HREF="#lbAG">multiHandle addhandle ?easyHandle?</A><DD>
|
|
<DT><A HREF="#lbAH">multiHandle removehandle ?easyHandle?</A><DD>
|
|
<DT><A HREF="#lbAI">multiHandle configure</A><DD>
|
|
<DT><A HREF="#lbAJ">multiHandle perform</A><DD>
|
|
<DT><A HREF="#lbAK">multiHandle active</A><DD>
|
|
<DT><A HREF="#lbAL">multiHandle getinfo</A><DD>
|
|
<DT><A HREF="#lbAM">multiHandle cleanup</A><DD>
|
|
<DT><A HREF="#lbAN">multiHandle auto ?-command <I>command</I>?</A><DD>
|
|
<DT><A HREF="#lbAO">curl::multistrerror errorCode</A><DD>
|
|
<DT><A HREF="#lbAP">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by man2html, using the manual pages.<BR>
|
|
</BODY>
|
|
</HTML>
|