doc/tclcurl_multi.html

   1 <HTML><HEAD><TITLE>Manpage of TclCurl</TITLE>
   2 </HEAD><BODY>
   3 <H1>TclCurl</H1>
   4 Section: TclCurl Multi Interface (n)<BR>Updated: 03 September 2011<BR><HR>
   5
   6 <A NAME="lbAB">&nbsp;</A>
   7 <H2>NAME</H2>
   8
   9 TclCurl: - get  a  URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE, LDAP,
  10 LDAPS, IMAP, IMAPS, POP, POP3, SMTP, SMTPS and gopher syntax.
  11 <A NAME="lbAC">&nbsp;</A>
  12 <H2>SYNOPSIS</H2>
  13
  14 <B>curl::multiinit</B>
  15
  16 <P>
  17 <I>multiHandle</I><B> addhandle</B>
  18
  19 <P>
  20 <I>multiHandle</I><B> removehandle</B>
  21
  22 <P>
  23 <I>multiHandle</I><B> configure</B>
  24
  25 <P>
  26 <I>multiHandle</I><B> perform</B>
  27
  28 <P>
  29 <I>multiHandle</I><B> active</B>
  30
  31 <P>
  32 <I>multiHandle</I><B> getinfo </B>
  33
  34 <P>
  35 <I>multihandle</I><B> cleanup</B>
  36
  37 <P>
  38 <I>multihandle</I><B> auto</B>
  39
  40 <P>
  41 <B>curl::multistrerror </B><I>errorCode</I>
  42
  43 <P>
  44 <A NAME="lbAD">&nbsp;</A>
  45 <H2>DESCRIPTION</H2>
  46
  47 TclCurl's multi interface introduces several new abilities that the easy
  48 interface refuses to offer. They are mainly:
  49 <ul>
  50 <li>Enable a &quot;pull&quot; interface. The application that uses TclCurl decides where
  51 and when to get/send data.<br><br>
  52 <li>Enable multiple simultaneous transfers in the same thread without making it
  53 complicated for the application.<br><br>
  54 <li>Keep Tk GUIs 'alive' while transfers are taking place.<br><br>
  55 </ul>
  56 <P>
  57 </DL>
  58 <A NAME="lbAE">&nbsp;</A>
  59 <H2>Blocking</H2>
  60
  61 A few areas in the code are still using blocking code, even when used from the
  62 multi interface. While we certainly want and intend for these to get fixed in
  63 the future, you should be aware of the following current restrictions:
  64 <ul>
  65 <li>Name resolves on non-windows unless c-ares is used.</B>
  66
  67 <li>GnuTLS SSL connections.</B>
  68
  69 <li>Active FTP connections.</B>
  70
  71 <li>HTTP proxy CONNECT operations.</B>
  72
  73 <li>SCP and SFTP connections.</B>
  74
  75 <li>SFTP transfers.</B>
  76
  77 <li>TFTP transfers</B>
  78
  79 <li>file:// transfers.</B>
  80 </ul>
  81
  82 <P>
  83 <A NAME="lbAF">&nbsp;</A>
  84 <H2>curl::multiinit</H2>
  85
  86 This procedure must be the first one to call, it returns a <I>multiHandle</I>
  87 that you need to use to invoke TclCurl procedures. The init MUST have a
  88 corresponding call to <I>cleanup</I> when the operation is completed.
  89 <P>
  90 <B>RETURN VALUE</B>
  91
  92 <P>
  93 <I>multiHandle</I>
  94
  95 to use.
  96 <P>
  97 <A NAME="lbAG">&nbsp;</A>
  98 <H2>multiHandle addhandle ?easyHandle?</H2>
  99
 100 <P>
 101 Each single transfer is built up with an 'easy' handle, the kind we have been
 102 using so far with TclCurl, you must create them and setup the appropriate
 103 options for each of them. Then we add them to the 'multi stack' using the
 104 <I>addhandle</I> command.
 105 <P>
 106 If the easy handle is not set to use a shared or global DNS cache, it will be made
 107 to use the DNS cache that is shared between all easy handles within the multi handle.
 108 <P>
 109 When an easy handle has been added to a multi stack, you can not and you must not use
 110 <I>perform</I> on that handle!
 111 <P>
 112 <P>
 113 <I>multiHandle</I>
 114
 115 is the return code from the <I>curl::multiinit</I> call.
 116 <P>
 117 <B>RETURN VALUE</B>
 118
 119 The possible return values are:
 120 <DL COMPACT>
 121 <DT>-1<DD>
 122 Handle added to the multi stack, please call
 123 <I>perform</I>
 124
 125 soon
 126 <DT>0<DD>
 127 Handle added ok.
 128 <DT>1<DD>
 129 Invalid multi handle.
 130 <DT>2<DD>
 131 Invalid 'easy' handle. It could mean that it isn't an easy handle at all, or possibly that
 132 the handle already is in used by this or another multi handle.
 133 <DT>3<DD>
 134 Out of memory, you should never get this.
 135 <DT>4<DD>
 136 You found a bug in TclCurl.
 137 <P>
 138 </DL>
 139 <A NAME="lbAH">&nbsp;</A>
 140 <H2>multiHandle removehandle ?easyHandle?</H2>
 141
 142 <P>
 143 When a transfer is done or if we want to stop a transfer before it is completed,
 144 we can use the <I>removehandle</I> command. Once removed from the multi handle,
 145 we can again use other easy interface functions on it.
 146 <P>
 147 Please note that when a single transfer is completed, the easy handle is still
 148 left added to the multi stack. You need to remove it and then close or, possibly,
 149 set new options to it and add it again to the multi handle to start another transfer.
 150 <P>
 151 <P>
 152 <B>RETURN VALUE</B>
 153
 154 The possible return values are:
 155 <DL COMPACT>
 156 <DT>0<DD>
 157 Handle removed ok.
 158 <DT>1<DD>
 159 Invalid multi handle.
 160 <DT>2<DD>
 161 Invalid 'easy' handle.
 162 <DT>3<DD>
 163 Out of memory, you should never get this.
 164 <DT>4<DD>
 165 You found a bug in TclCurl.
 166 <P>
 167 </DL>
 168 <A NAME="lbAI">&nbsp;</A>
 169 <H2>multiHandle configure</H2>
 170
 171 So far the only option is:
 172 <DL COMPACT>
 173 <DT><B>-pipelining</B>
 174
 175 <DD>
 176 Pass a 1 to enable or 0 to disable. Enabling pipelining on a multi handle will
 177 make it attempt to perform HTTP Pipelining as far as possible for transfers using
 178 this handle. This means that if you add a second request that can use an already
 179 existing connection, the second request will be &quot;piped&quot; on the same connection
 180 rather than being executed in parallel.
 181 <DT><B>-maxconnects</B>
 182
 183 <DD>
 184 Pass a number which will be used as the maximum amount of simultaneously open
 185 connections that TclCurl may cache. Default is 10, and TclCurl will enlarge
 186 the size for each added easy handle to make it fit 4 times the number of added
 187 easy handles.
 188 <P>
 189 By setting this option, you can prevent the cache size to grow beyond the limit
 190 set by you. When the cache is full, curl closes the oldest one in the cache to
 191 prevent the number of open connections to increase.
 192 <P>
 193 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.
 194 <P>
 195 </DL>
 196 <A NAME="lbAJ">&nbsp;</A>
 197 <H2>multiHandle perform</H2>
 198
 199 Adding the easy handles to the multi stack does not start any transfer.
 200 Remember that one of the main ideas with this interface is to let your
 201 application drive. You drive the transfers by invoking
 202 <I>perform.</I>
 203
 204 TclCurl will then transfer data if there is anything available to transfer.
 205 It'll use the callbacks and everything else we have setup in the individual
 206 easy handles. It'll transfer data on all current transfers in the multi stack
 207 that are ready to transfer anything. It may be all, it may be none.
 208 <P>
 209 When you call <B>perform</B> and the amount of Irunning handles is
 210 changed from the previous call (or is less than the amount of easy handles
 211 you added to the multi handle), you know that there is one or more
 212 transfers less &quot;running&quot;. You can then call <I>getinfo</I> to
 213 get information about each individual completed transfer.
 214 <P>
 215 <B>RETURN VALUE</B>
 216
 217 If everything goes well, it returns the number of running handles, '0' if all
 218 are done. In case of error, it will return the error code.
 219 <P>
 220 <A NAME="lbAK">&nbsp;</A>
 221 <H2>multiHandle active</H2>
 222
 223 In order to know if any of the easy handles are ready to transfer data before
 224 invoking
 225 <I>perform</I>
 226
 227 you can use the
 228 <I>active</I>
 229
 230 command, it will return the number of transfers currently active.
 231 <P>
 232 <B>RETURN VALUE</B>
 233
 234 The number of active transfers or '-1' in case of error.
 235 <P>
 236 <A NAME="lbAL">&nbsp;</A>
 237 <H2>multiHandle getinfo</H2>
 238
 239 This procedure returns very simple information about the transfers, you
 240 can get more detail information using the <I>getinfo</I>
 241 command on each of the easy handles.
 242 <P>
 243 <P>
 244 <B>RETURN VALUE</B>
 245
 246 A list with the following elements:
 247 <DL COMPACT>
 248 <DT>easyHandle about which the info is about.<DD>
 249 <DT>state of the transfer, '1' if it is done.<DD>
 250 <DT>exit code of the transfer, '0' if there was no error,...<DD>
 251 <DT>Number of messages still in the info queue.<DD>
 252 <DT>In case there are no messages in the queue it will return {&quot;&quot; 0 0 0}.<DD>
 253 <P>
 254 </DL>
 255 <A NAME="lbAM">&nbsp;</A>
 256 <H2>multiHandle cleanup</H2>
 257
 258 This procedure must be the last one to call for a multi stack, it is the opposite of the
 259 <I>curl::multiinit</I>
 260
 261 procedure and must be called with the same
 262 <I>multiHandle</I>
 263
 264 as input as the
 265 <B>curl::multiinit</B>
 266
 267 call returned.
 268 <P>
 269 <A NAME="lbAN">&nbsp;</A>
 270 <H2>multiHandle auto ?-command <I>command</I>?</H2>
 271
 272 Using this command Tcl's event loop will take care of periodically invoking <B>perform</B>
 273 for you, before using it, you must have already added at least one easy handle to
 274 the multi handle.
 275 <P>
 276 The <B>command</B> option allows you to specify a command to invoke after all the easy
 277 handles have finished their transfers, even though I say it is an option, the truth is
 278 you must use this command to cleanup all the handles, otherwise the transfered files
 279 may not be complete.
 280 <P>
 281 This support is still in a very experimental state, it may still change without warning.
 282 Any and all comments are welcome.
 283 <P>
 284 You can find a couple of examples at <B>tests/multi</B>.
 285 <P>
 286 <A NAME="lbAO">&nbsp;</A>
 287 <H2>curl::multistrerror errorCode</H2>
 288
 289 This procedure returns a string describing the error code passed in the argument.
 290 <P>
 291 <A NAME="lbAP">&nbsp;</A>
 292 <H2>SEE ALSO</H2>
 293
 294 <I>tclcurl, curl.</I>
 295
 296 <P>
 297
 298 <HR>
 299 <A NAME="index">&nbsp;</A><H2>Index</H2>
 300 <DL>
 301 <DT><A HREF="#lbAB">NAME</A><DD>
 302 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
 303 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
 304 <DT><A HREF="#lbAE">Blocking</A><DD>
 305 <DT><A HREF="#lbAF">curl::multiinit</A><DD>
 306 <DT><A HREF="#lbAG">multiHandle addhandle ?easyHandle?</A><DD>
 307 <DT><A HREF="#lbAH">multiHandle removehandle ?easyHandle?</A><DD>
 308 <DT><A HREF="#lbAI">multiHandle configure</A><DD>
 309 <DT><A HREF="#lbAJ">multiHandle perform</A><DD>
 310 <DT><A HREF="#lbAK">multiHandle active</A><DD>
 311 <DT><A HREF="#lbAL">multiHandle getinfo</A><DD>
 312 <DT><A HREF="#lbAM">multiHandle cleanup</A><DD>
 313 <DT><A HREF="#lbAN">multiHandle auto ?-command <I>command</I>?</A><DD>
 314 <DT><A HREF="#lbAO">curl::multistrerror errorCode</A><DD>
 315 <DT><A HREF="#lbAP">SEE ALSO</A><DD>
 316 </DL>
 317 <HR>
 318 This document was created by man2html, using the manual pages.<BR>
 319 </BODY>
 320 </HTML>