wrath/shaniqua-tclcurl-fa
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

initial checkin of TclCurl

Browse Source
This commit is contained in:
Steve Havelka
2014-02-05 16:43:59 -08:00
commit 639b49517b
95 changed files with 30934 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
doc/OpenSSL-LICENSE.txt Executable file
View File

@ -0,0 +1,127 @@
LICENSE ISSUES
==============
The OpenSSL toolkit stays under a dual license, i.e. both the conditions of
the OpenSSL License and the original SSLeay license apply to the toolkit.
See below for the actual license texts. Actually both licenses are BSD-style
Open Source licenses. In case of any license issues related to OpenSSL
please contact openssl-core@openssl.org.
OpenSSL License
---------------
/* ====================================================================
* Copyright (c) 1998-2001 The OpenSSL Project. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. All advertising materials mentioning features or use of this
* software must display the following acknowledgment:
* "This product includes software developed by the OpenSSL Project
* for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
*
* 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
* endorse or promote products derived from this software without
* prior written permission. For written permission, please contact
* openssl-core@openssl.org.
*
* 5. Products derived from this software may not be called "OpenSSL"
* nor may "OpenSSL" appear in their names without prior written
* permission of the OpenSSL Project.
*
* 6. Redistributions of any form whatsoever must retain the following
* acknowledgment:
* "This product includes software developed by the OpenSSL Project
* for use in the OpenSSL Toolkit (http://www.openssl.org/)"
*
* THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
* EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
* ====================================================================
*
* This product includes cryptographic software written by Eric Young
* (eay@cryptsoft.com). This product includes software written by Tim
* Hudson (tjh@cryptsoft.com).
*
*/
Original SSLeay License
-----------------------
/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
* All rights reserved.
*
* This package is an SSL implementation written
* by Eric Young (eay@cryptsoft.com).
* The implementation was written so as to conform with Netscapes SSL.
*
* This library is free for commercial and non-commercial use as long as
* the following conditions are aheared to. The following conditions
* apply to all code found in this distribution, be it the RC4, RSA,
* lhash, DES, etc., code; not just the SSL code. The SSL documentation
* included with this distribution is covered by the same copyright terms
* except that the holder is Tim Hudson (tjh@cryptsoft.com).
*
* Copyright remains Eric Young's, and as such any Copyright notices in
* the code are not to be removed.
* If this package is used in a product, Eric Young should be given attribution
* as the author of the parts of the library used.
* This can be in the form of a textual message at program startup or
* in documentation (online or textual) provided with the package.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. All advertising materials mentioning features or use of this software
* must display the following acknowledgement:
* "This product includes cryptographic software written by
* Eric Young (eay@cryptsoft.com)"
* The word 'cryptographic' can be left out if the rouines from the library
* being used are not cryptographic related :-).
* 4. If you include any Windows specific code (or a derivative thereof) from
* the apps directory (application code) you must include an acknowledgement:
* "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
*
* THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* The licence and distribution terms for any publically available version or
* derivative of this code cannot be changed. i.e. this code cannot simply be
* copied and put under another distribution licence
* [including the GNU Public Licence.]
*/

64
doc/aolserver.txt Executable file
View File

@ -0,0 +1,64 @@
There are a number of issues with namespaces in AOLserver 3.x, which I believe
are fixed in 4.0, which should be released within a few months. But in the
meantime this is what we've had to do for AOLserver 3.2 on Windows 2000.
Alex Khassin
1. Under [ns_library shared] directory, create a directory called
packages.
2. Register this directory as a Tcl module in nsd.tcl:
ns_section "ns/server/${servername}/modules"
ns_param packages Tcl
3. Place each package into a subdirectory of the same name as the
package name (i.e. [ns_library shared]/packages/TclCurl)
4. Copy S:\NaviSoft\Server\modules\tcl\am\packages.init.tcl to the
[ns_library shared]/packages directory and rename to just init.tcl
5. Under AOLserver 4.x (and hopefully in 3.5.x) add to the bottom
of this file appropriate commands to register each package:
_am_pregister shared <packageName>
6. In your code, when you need to use a particular package, instead
of 'package require <packageName>', execute 'am_pinit <packageName>'
7. This will use the existing package registration under AOLserver
4.x and, under AOLserver 3.2, it will first register the package
in this interpreter and then use it.
8. This is necessary because in AOLserver 3.2, namespaces aren't
properly imported into child interpreters.
Currently dnscrub.com is set up like this for TclCurl and it works.
Example usage:
am_pinit TclCurl
curl::transfer -url http://am.net/index.htm -file d:/test.htm
FYI, the code for am_pinit and _am_pregister procs:
proc am_pinit {package} {
# AOLserver 3.2 package/namespace-handling is broken
# (namespace/packages don't get imported into child interpreters)
# so use this workaround proc instead of 'package require' to
# load the package into the current interpreter
# (this is obviously slower than copying from master interpeter)
# Package names are case-sensitive!
# Returns the version of the loaded package
set library shared
if {[lsearch -exact [package names] $package] == -1} {
ns_log Notice "packages: registering $library/$package"
_am_pregister $library $package
}
package require $package
}
proc _am_pregister {library package} {
# Registers the package. library is 'shared' or 'private'
set dir [ns_library $library]/packages/$package
source $dir/pkgIndex.tcl
}

3141
doc/tclcurl.html Executable file
View File

File diff suppressed because it is too large Load Diff

2579
doc/tclcurl.n Executable file
View File

File diff suppressed because it is too large Load Diff

320
doc/tclcurl_multi.html Executable file
View File

@ -0,0 +1,320 @@
<HTML><HEAD><TITLE>Manpage of TclCurl</TITLE>
</HEAD><BODY>
<H1>TclCurl</H1>
Section: TclCurl Multi Interface (n)<BR>Updated: 03 September 2011<BR><HR>
<A NAME="lbAB">&nbsp;</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">&nbsp;</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">&nbsp;</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 &quot;pull&quot; 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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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 &quot;piped&quot; 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">&nbsp;</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 &quot;running&quot;. 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">&nbsp;</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">&nbsp;</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 {&quot;&quot; 0 0 0}.<DD>
<P>
</DL>
<A NAME="lbAM">&nbsp;</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">&nbsp;</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">&nbsp;</A>
<H2>curl::multistrerror errorCode</H2>
This procedure returns a string describing the error code passed in the argument.
<P>
<A NAME="lbAP">&nbsp;</A>
<H2>SEE ALSO</H2>
<I>tclcurl, curl.</I>
<P>
<HR>
<A NAME="index">&nbsp;</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>

238
doc/tclcurl_multi.n Executable file
View File

@ -0,0 +1,238 @@
.\" You can view this file with:
.\" nroff -man [file]
.\" Adapted from libcurl docs by fandom@telefonica.net
.TH TclCurl n "3 October 2011" "TclCurl 7.22.0 "TclCurl Easy Interface"
.SH NAME
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.
.SH SYNOPSIS
.BI "curl::multiinit"
.sp
.IB multiHandle " addhandle"
.sp
.IB multiHandle " removehandle"
.sp
.IB multiHandle " configure"
.sp
.IB multiHandle " perform"
.sp
.IB multiHandle " active"
.sp
.IB multiHandle " getinfo "
.sp
.IB multihandle " cleanup"
.sp
.IB multihandle " auto"
.sp
.BI "curl::multistrerror " errorCode
.sp
.SH DESCRIPTION
TclCurl's multi interface introduces several new abilities that the easy
interface refuses to offer. They are mainly:
.TP
Enable a "pull" interface. The application that uses TclCurl decides where and when to get/send data.
.TP
Enable multiple simultaneous transfers in the same thread without making it complicated for the application.
.TP
Keep Tk GUIs 'alive' while transfers are taking place.
.SH 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:
.RS
.TP 5
.B Name resolves on non-windows unless c-ares is used.
.TP
.B GnuTLS SSL connections.
.TP
.B GnuTLS SSL connections
.TP
.B Active FTP connections.
.TP
.B HTTP proxy CONNECT operations.
.TP
.B SOCKS proxy handshakes
.TP
.B file:// transfers.
.TP
.B TELNET transfers
.RE
.SH curl::multiinit
This procedure must be the first one to call, it returns a \fImultiHandle\fP
that you need to use to invoke TclCurl procedures. The init MUST have a
corresponding call to \fIcleanup\fP when the operation is completed.
.sp
.B RETURN VALUE
.sp
.I multiHandle
to use.
.sp
.SH multiHandle addhandle ?easyHandle?
.sp
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
\fIaddhandle\fP 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
\fIperform\fP on that handle!
.sp
.I "multiHandle"
is the return code from the \fIcurl::multiinit\fP call.
.sp
.B RETURN VALUE
The possible return values are:
.IP -1
Handle added to the multi stack, please call
.I perform
soon
.IP 0
Handle added ok.
.IP 1
Invalid multi handle.
.IP 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.
.IP 3
Out of memory, you should never get this.
.IP 4
You found a bug in TclCurl.
.sp
.SH multiHandle removehandle ?easyHandle?
.sp
When a transfer is done or if we want to stop a transfer before it is completed,
we can use the \fIremovehandle\fP 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.
.sp
.B RETURN VALUE
The possible return values are:
.IP 0
Handle removed ok.
.IP 1
Invalid multi handle.
.IP 2
Invalid 'easy' handle.
.IP 3
Out of memory, you should never get this.
.IP 4
You found a bug in TclCurl.
.sp
.SH multiHandle configure
So far the only options are:
.TP
.B -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.
.TP
.B -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 \fBmaxconnects\fP option.
.sp
.SH 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
.I 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 \fBperform\fP and the amount of running 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 \fIgetinfo\fP to
get information about each individual completed transfer. If an added handle
fails very quickly, it may never be counted as a running handle.
.sp
.B 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.
This function only returns errors etc regarding the whole multi stack.
Problems still might have occurred on individual transfers even when this
function returns ok.
.sp
.SH multiHandle active
In order to know if any of the easy handles are ready to transfer data before
invoking
.I perform
you can use the
.I active
command, it will return the number of transfers currently active.
.sp
.B RETURN VALUE
The number of active transfers or '-1' in case of error.
.SH multiHandle getinfo
This procedure returns very simple information about the transfers, you
can get more detail information using the \fIgetinfo\fP
command on each of the easy handles.
.sp
.B RETURN VALUE
A list with the following elements:
.TP
easyHandle about which the info is about.
.TP
state of the transfer, '1' if it is done.
.TP
exit code of the transfer, '0' if there was no error,...
.TP
Number of messages still in the info queue.
.TP
In case there are no messages in the queue it will return {"" 0 0 0}.
.SH multiHandle cleanup
This procedure must be the last one to call for a multi stack, it is the opposite of the
.I curl::multiinit
procedure and must be called with the same
.I multiHandle
as input as the
.B curl::multiinit
call returned.
.SH multiHandle auto ?-command \fIcommand\fP?
Using this command Tcl's event loop will take care of periodically invoking \fBperform\fP
for you, before using it, you must have already added at least one easy handle to
the multi handle.
The \fBcommand\fP 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 \fBtests/multi\fP.
.SH curl::multistrerror errorCode
This procedure returns a string describing the error code passed in the argument.
.SH "SEE ALSO"
.I tclcurl, curl.

112
doc/tclcurl_share.html Executable file
View File

@ -0,0 +1,112 @@
<HTML><HEAD><TITLE>Manpage of TclCurl</TITLE>
</HEAD><BODY>
<H1>TclCurl</H1>
Section: TclCurl share data api (n)<BR>Updated: 03 October 2011<BR><HR>
<A NAME="lbAB">&nbsp;</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">&nbsp;</A>
<H2>SYNOPSIS</H2>
<B>curl::shareinit</B>
<P>
<I>shareHandle</I><B> share </B><I>?data?</I>
<P>
<I>shareHandle</I><B> unshare </B><I>?data?</I>
<P>
<I>shareHandle</I><B> cleanup</B>
<P>
<B>curl::sharestrerror </B><I>errorCode</I>
<P>
<P>
<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>
<P>
With the share API, you can have two or more 'easy' handles sharing data
among them, so far they can only share cookies and DNS data.
<P>
<A NAME="lbAE">&nbsp;</A>
<H2>curl::shareinit</H2>
This procedure must be the first one to call, it returns a <B>shareHandle</B>
that you need to use to share data among handles using the <B>-share</B> option
to the <B>configure</B> command. The init MUST have a corresponding call to
<B>cleanup</B> when the operation is completed.
<P>
<B>RETURN VALUE</B>
<P>
<B>shareHandle</B> to use.
<P>
<A NAME="lbAF">&nbsp;</A>
<H2>shareHandle share ?data?</H2>
<P>
The parameter specifies a type of data that should be shared. This may be set
to one of the values described below:
<P>
<DL COMPACT><DT><DD>
<DL COMPACT>
<DT><B>cookies</B>
<DD>
Cookie data will be shared across the easy handles using this shared object.
<P>
<DT><B>dns</B>
<DD>
Cached DNS hosts will be shared across the easy handles using this shared object.
</DL>
</DL>
<P>
<A NAME="lbAG">&nbsp;</A>
<H2>shareHandle unshare ?data?</H2>
This command does the opposite of <B>share</B>. The specified parameter will no
longer be shared. Valid values are the same as those for <B>share</B>.
<P>
<A NAME="lbAH">&nbsp;</A>
<H2>sharehandle cleanup</H2>
<P>
Deletes a shared object. The share handle cannot be used anymore after this
function has been called.
<P>
<A NAME="lbAI">&nbsp;</A>
<H2>curl::sharestrerror errorCode</H2>
Returns a string describing the error code passed in the argument.
<P>
<A NAME="lbAJ">&nbsp;</A>
<H2>SEE ALSO</H2>
<I>curl, TclCurl</I>
<P>
<HR>
<A NAME="index">&nbsp;</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">curl::shareinit</A><DD>
<DT><A HREF="#lbAF">shareHandle share ?data?</A><DD>
<DT><A HREF="#lbAG">shareHandle unshare ?data?</A><DD>
<DT><A HREF="#lbAH">sharehandle cleanup</A><DD>
<DT><A HREF="#lbAI">curl::sharestrerror errorCode</A><DD>
<DT><A HREF="#lbAJ">SEE ALSO</A><DD>
</DL>
<HR>
This document was created by man2html, using the manual pages.<BR>
</BODY>
</HTML>

65
doc/tclcurl_share.n Executable file
View File

@ -0,0 +1,65 @@
.\" You can view this file with:
.\" nroff -man [file]
.\" Adapted from libcurl docs by fandom@telefonica.net
.TH TclCurl n "3 October 2011" "TclCurl 7.22.0 "TclCurl Easy Interface"
.SH NAME
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.
.SH SYNOPSIS
.BI "curl::shareinit"
.sp
.IB shareHandle " share " "?data?"
.sp
.IB shareHandle " unshare " "?data?"
.sp
.IB shareHandle " cleanup"
.sp
.BI "curl::sharestrerror " errorCode
.SH DESCRIPTION
With the share API, you can have two or more 'easy' handles sharing data
among them, so far they can only share cookies and DNS data.
.SH curl::shareinit
This procedure must be the first one to call, it returns a \fBshareHandle\fP
that you need to use to share data among handles using the \fB-share\fP option
to the \fBconfigure\fP command. The init MUST have a corresponding call to
\fBcleanup\fP when the operation is completed.
.B RETURN VALUE
.sp
\fBshareHandle\fP to use.
.SH shareHandle share ?data?
The parameter specifies a type of data that should be shared. This may be set
to one of the values described below:
.RS
.TP 5
.B cookies
Cookie data will be shared across the easy handles using this shared object.
.TP
.B dns
Cached DNS hosts will be shared across the easy handles using this shared object.
Note that when you use the multi interface, all easy handles added to the same multi
handle will share DNS cache by default without this having to be used!
.RE
.SH shareHandle unshare ?data?
This command does the opposite of \fBshare\fP. The specified parameter will no
longer be shared. Valid values are the same as those for \fBshare\fP.
.SH sharehandle cleanup
Deletes a shared object. The share handle cannot be used anymore after this
function has been called.
.SH curl::sharestrerror errorCode
Returns a string describing the error code passed in the argument.
.SH "SEE ALSO"
.I curl, TclCurl