X-Git-Url: https://git.sven.stormbind.net/?a=blobdiff_plain;f=doc%2FSinComprimir%2Ftclcurl_multi.n;fp=doc%2FSinComprimir%2Ftclcurl_multi.n;h=0000000000000000000000000000000000000000;hb=b62db6a104a211b14dc512cbb9cbcea49613ff19;hp=933d00d0a86afc6b47dc6b33df14023adf543429;hpb=b0e6fb6e4379fb87fa2854b84a56c5ad49c644da;p=sven%2Ftclcurl.git diff --git a/doc/SinComprimir/tclcurl_multi.n b/doc/SinComprimir/tclcurl_multi.n deleted file mode 100644 index 933d00d..0000000 --- a/doc/SinComprimir/tclcurl_multi.n +++ /dev/null @@ -1,226 +0,0 @@ -.\" 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.