TclCurl
Section: TclCurl Multi Interface (n)
Updated: 25 June 2002
NAME
TclCurl: - get a URL with FTP, TELNET, LDAP, GOPHER, DICT, FILE, HTTP or HTTPS syntax.
SYNOPSIS
curl::multiinit
multiHandle addhandle easyHandle
multiHandle removehandle easyHandle
multiHandle perform
multiHandle active
multiHandle getinfo
multihandle cleanup
DESCRIPTION
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.
-
curl::multiinit
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.
multiHandle addhandle easyHandle
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.
multiHandle removehandle easyHandle
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.
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
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.
RETURN VALUE
If everything goes well, it returns the number of running handles.
The possible return values if there is an error are:
- 0
-
Transfers done.
- 1
-
Invalid multi handle.
multiHandle active
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.
multiHandle getinfo
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.
-
-
-
- The exit code of the transfer.
-
- Number of messages still in the info queue.
-
- In case there are no messages in the queue it will return {"" 0 0 0}.
-
curlHandle cleanup
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.
SEE ALSO
tclcurl, curl.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- curl::multiinit
-
- multiHandle addhandle ?easyHandle?
-
- multiHandle removehandle ?easyHandle?
-
- multiHandle perform
-
- multiHandle active
-
- multiHandle getinfo
-
- curlHandle cleanup
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 00:12:32 GMT, June 25, 2002