TclCurl: - get a URL with FTP, TELNET, LDAP, GOPHER, DICT, FILE, HTTP or HTTPS syntax.

curl::multiinit multiHandle addhandle multiHandle removehandle multiHandle perform multiHandle active multiHandle getinfo multihandle cleanup multihandle auto curl::multistrerror errorCode

TclCurl's multi interface introduces several new abilities that the easy interface refuses to offer. They are mainly:

Enable a "pull" interface. The application that uses TclCurl decides where

and when to get/send data.

Enable multiple simultaneous transfers in the same thread without making it

complicated for the application.

Keep Tk GUIs 'alive' while transfers are taking place.

This procedure must be the first one to call, it returns a multiHandle that you need to use to invoke TclCurl procedures. The init MUST have a corresponding call to cleanup when the operation is completed. RETURN VALUE multiHandle to use.

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 addhandle command. multiHandle is the return code from the curl::multiinit call. RETURN VALUE The possible return values are:

-1

Handle added to the multi stack, please call perform soon

0

Handle added ok.

1

Invalid multi handle.

2

Invalid 'easy' handle.

3

Out of memory, you should never get this.

4

You found a bug in TclCurl.

When a transfer is done or if we want to stop a transfer before it is completed, we can use the removehandle command. Once removed from the multi handle, we can again use other easy interface functions on it. RETURN VALUE The possible return values are:

0

Handle removed ok.

1

Invalid multi handle.

2

Invalid 'easy' handle.

3

Out of memory, you should never get this.

4

You found a bug in TclCurl.

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 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 perform 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 getinfo to get information about each individual completed transfer.

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.

In order to know if any of the easy handles are ready to transfer data before invoking perform you can use the active command, it will return the number of transfers currently active. RETURN VALUE The number of active transfers or '-1' in case of error.

This procedure returns very simple information about the transfers, you can get more detail information using the getinfo command on each of the easy handles. RETURN VALUE A list with the following elements:

easyHandle about which the info is about.

state of the transfer, '1' if it is done.

exit code of the transfer, '0' if there was no error,...

Number of messages still in the info queue.

In case there are no messages in the queue it will return {"" 0 0 0}.

This procedure must be the last one to call for a multi stack, it is the opposite of the curl::multiinit procedure and must be called with the same multiHandle as input as the curl::multiinit call returned.

Using this command Tcl's event loop will take care of periodically invoking perform for you, before using it, you must have already added at least one easy handle to the multi handle.

The command 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 tests/multi.

This procedure returns a string describing the error code passed in the argument.

tclcurl, curl.