+++ /dev/null
-.\" You can view this file with:
-.\" nroff -man [file]
-.\" Adapted from libcurl docs by fandom@telefonica.net
-.TH TclCurl n "8 September 2008" "TclCurl 7.19.0" "TclCurl Multi Interface"
-.SH NAME
-TclCurl: - get a URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE or LDAP 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 Active FTP connections.
-.TP
-.B HTTP proxy CONNECT operations.
-.TP
-.B TFTP transfers
-.TP
-.B file:// 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 option is:
-.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 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 \fIgetinfo\fP to
-get information about each individual completed transfer.
-.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.
-.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.
projects / sven / tclcurl.git / blobdiff