doc/tclcurl_multi.n

   1 .\" You can view this file with:
   2 .\" nroff -man [file]
   3 .\" Adapted from libcurl docs by fandom@telefonica.net
   4 .TH TclCurl n "3 October 2011" "TclCurl 7.22.0 "TclCurl Easy Interface"
   5 .SH NAME
   6 TclCurl: - get  a  URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE, LDAP,
   7 LDAPS, IMAP, IMAPS, POP, POP3, SMTP, SMTPS and gopher syntax.
   8 .SH SYNOPSIS
   9 .BI "curl::multiinit"
  10 .sp
  11 .IB multiHandle " addhandle"
  12 .sp
  13 .IB multiHandle " removehandle"
  14 .sp
  15 .IB multiHandle " configure"
  16 .sp
  17 .IB multiHandle " perform"
  18 .sp
  19 .IB multiHandle " active"
  20 .sp
  21 .IB multiHandle " getinfo "
  22 .sp
  23 .IB multihandle " cleanup"
  24 .sp
  25 .IB multihandle " auto"
  26 .sp
  27 .BI "curl::multistrerror " errorCode
  28 .sp
  29 .SH DESCRIPTION
  30 TclCurl's multi interface introduces several new abilities that the easy
  31 interface refuses to offer. They are mainly:
  32 .TP
  33 Enable a "pull" interface. The application that uses TclCurl decides where and when to get/send data.
  34 .TP
  35 Enable multiple simultaneous transfers in the same thread without making it complicated for the application.
  36 .TP
  37 Keep Tk GUIs 'alive' while transfers are taking place.
  38
  39 .SH Blocking
  40 A few areas in the code are still using blocking code, even when used from the
  41 multi interface. While we certainly want and intend for these to get fixed in
  42 the future, you should be aware of the following current restrictions:
  43 .RS
  44 .TP 5
  45 .B Name resolves on non-windows unless c-ares is used.
  46 .TP
  47 .B GnuTLS SSL connections.
  48 .TP
  49 .B GnuTLS SSL connections
  50 .TP
  51 .B Active FTP connections.
  52 .TP
  53 .B HTTP proxy CONNECT operations.
  54 .TP
  55 .B SOCKS proxy handshakes
  56 .TP
  57 .B file:// transfers.
  58 .TP
  59 .B TELNET transfers
  60 .RE
  61
  62 .SH curl::multiinit
  63 This procedure must be the first one to call, it returns a \fImultiHandle\fP
  64 that you need to use to invoke TclCurl procedures. The init MUST have a
  65 corresponding call to \fIcleanup\fP when the operation is completed.
  66 .sp
  67 .B RETURN VALUE
  68 .sp
  69 .I multiHandle
  70 to use.
  71 .sp
  72 .SH multiHandle addhandle ?easyHandle?
  73 .sp
  74 Each single transfer is built up with an 'easy' handle, the kind we have been
  75 using so far with TclCurl, you must create them and setup the appropriate
  76 options for each of them. Then we add them to the 'multi stack' using the
  77 \fIaddhandle\fP command.
  78
  79 If the easy handle is not set to use a shared or global DNS cache, it will be made
  80 to use the DNS cache that is shared between all easy handles within the multi handle.
  81
  82 When an easy handle has been added to a multi stack, you can not and you must not use
  83 \fIperform\fP on that handle!
  84
  85 .sp
  86 .I "multiHandle"
  87 is the return code from the \fIcurl::multiinit\fP call.
  88 .sp
  89 .B RETURN VALUE
  90 The possible return values are:
  91 .IP -1
  92 Handle added to the multi stack, please call
  93 .I perform
  94 soon
  95 .IP 0
  96 Handle added ok.
  97 .IP 1
  98 Invalid multi handle.
  99 .IP 2
 100 Invalid 'easy' handle. It could mean that it isn't an easy handle at all, or possibly that
 101 the handle already is in used by this or another multi handle.
 102 .IP 3
 103 Out of memory, you should never get this.
 104 .IP 4
 105 You found a bug in TclCurl.
 106 .sp
 107 .SH multiHandle removehandle ?easyHandle?
 108 .sp
 109 When a transfer is done or if we want to stop a transfer before it is completed,
 110 we can use the \fIremovehandle\fP command. Once removed from the multi handle,
 111 we can again use other easy interface functions on it.
 112
 113 Please note that when a single transfer is completed, the easy handle is still
 114 left added to the multi stack. You need to remove it and then close or, possibly,
 115 set new options to it and add it again to the multi handle to start another transfer.
 116
 117 .sp
 118 .B RETURN VALUE
 119 The possible return values are:
 120 .IP 0
 121 Handle removed ok.
 122 .IP 1
 123 Invalid multi handle.
 124 .IP 2
 125 Invalid 'easy' handle.
 126 .IP 3
 127 Out of memory, you should never get this.
 128 .IP 4
 129 You found a bug in TclCurl.
 130 .sp
 131 .SH multiHandle configure
 132 So far the only options are:
 133 .TP
 134 .B -pipelining
 135 Pass a 1 to enable or 0 to disable. Enabling pipelining on a multi handle will
 136 make it attempt to perform HTTP Pipelining as far as possible for transfers using
 137 this handle. This means that if you add a second request that can use an already
 138 existing connection, the second request will be "piped" on the same connection
 139 rather than being executed in parallel.
 140 .TP
 141 .B -maxconnects
 142 Pass a number which will be used as the maximum amount of simultaneously open
 143 connections that TclCurl may cache. Default is 10, and TclCurl will enlarge
 144 the size for each added easy handle to make it fit 4 times the number of added
 145 easy handles.
 146
 147 By setting this option, you can prevent the cache size to grow beyond the limit
 148 set by you. When the cache is full, curl closes the oldest one in the cache to
 149 prevent the number of open connections to increase.
 150
 151 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.
 152 .sp
 153 .SH multiHandle perform
 154 Adding the easy handles to the multi stack does not start any transfer.
 155 Remember that one of the main ideas with this interface is to let your
 156 application drive. You drive the transfers by invoking
 157 .I perform.
 158 TclCurl will then transfer data if there is anything available to transfer.
 159 It'll use the callbacks and everything else we have setup in the individual
 160 easy handles. It'll transfer data on all current transfers in the multi stack
 161 that are ready to transfer anything. It may be all, it may be none.
 162
 163 When you call \fBperform\fP and the amount of running handles is
 164 changed from the previous call (or is less than the amount of easy handles
 165 you added to the multi handle), you know that there is one or more
 166 transfers less "running". You can then call \fIgetinfo\fP to
 167 get information about each individual completed transfer. If an added handle
 168 fails very quickly, it may never be counted as a running handle.
 169
 170 .sp
 171 .B RETURN VALUE
 172 If everything goes well, it returns the number of running handles, '0' if all
 173 are done. In case of error, it will return the error code.
 174
 175 This function only returns errors etc regarding the whole multi stack.
 176 Problems still might have occurred on individual transfers even when this
 177 function returns ok.
 178
 179 .sp
 180 .SH multiHandle active
 181 In order to know if any of the easy handles are ready to transfer data before
 182 invoking
 183 .I perform
 184 you can use the
 185 .I active
 186 command, it will return the number of transfers currently active.
 187 .sp
 188 .B RETURN VALUE
 189 The number of active transfers or '-1' in case of error.
 190
 191 .SH multiHandle getinfo
 192 This procedure returns very simple information about the transfers, you
 193 can get more detail information using the \fIgetinfo\fP
 194 command on each of the easy handles.
 195
 196 .sp
 197 .B RETURN VALUE
 198 A list with the following elements:
 199 .TP
 200 easyHandle about which the info is about.
 201 .TP
 202 state of the transfer, '1' if it is done.
 203 .TP
 204 exit code of the transfer, '0' if there was no error,...
 205 .TP
 206 Number of messages still in the info queue.
 207 .TP
 208 In case there are no messages in the queue it will return {"" 0 0 0}.
 209
 210 .SH multiHandle cleanup
 211 This procedure must be the last one to call for a multi stack, it is the opposite of the
 212 .I curl::multiinit
 213 procedure and must be called with the same
 214 .I multiHandle
 215 as input as the
 216 .B curl::multiinit
 217 call returned.
 218
 219 .SH multiHandle auto ?-command \fIcommand\fP?
 220 Using this command Tcl's event loop will take care of periodically invoking \fBperform\fP
 221 for you, before using it, you must have already added at least one easy handle to
 222 the multi handle.
 223
 224 The \fBcommand\fP option allows you to specify a command to invoke after all the easy
 225 handles have finished their transfers, even though I say it is an option, the truth is
 226 you must use this command to cleanup all the handles, otherwise the transfered files
 227 may not be complete.
 228
 229 This support is still in a very experimental state, it may still change without warning.
 230 Any and all comments are welcome.
 231
 232 You can find a couple of examples at \fBtests/multi\fP.
 233
 234 .SH curl::multistrerror errorCode
 235 This procedure returns a string describing the error code passed in the argument.
 236
 237 .SH "SEE ALSO"
 238 .I tclcurl, curl.