Re: the new 'multi' API
Date: Sat, 3 Nov 2001 16:32:17 +0100 (MET)
On Tue, 30 Oct 2001, Daniel Stenberg wrote:
> o How to deal with errors on single transfers.
In the absence of feedback, I suggest the following approach. I also updated
the multi.h file in the dev section on the web. Would it work? Is it good
enough? What's bad with it? You know a better way? Throw in your suggestions
here. Nothing here is set in stone.
* I suggest a synchronous system to get information from the multi system.
* I've named these functions "curl_multi_info*" something to make it apparent
* that they belong together.
* I expect that the curl_multi_info_open will be used fairly often after
* calls to curl_multi_perform(), but there's nothing in this design that
* forces the application to invoke it at that particular time. In fact, many
* application will do good without using it at all.
* Desc: Ask the multi handle if there's any messages/informationals from
* the individual transfers. We pass a pointer to a 'CURLMinfo' that
* can be used as input in a subsequent call to curl_multi_info_read.
* Messages include informationals such as error code from the
* transfer or just the fact that a transfer is completed. More
* details on these should be written down as well.
* Name: curl_multi_info()
* Returns: The number of transfers that have information stored that can be
* read. If zero is returned, there's no need to call
* curl_multi_info_close() on the returned handle, but there's no
* harm in doing so.
int curl_multi_info_open(CURLM multi_handle, CURLMinfo *info_handle);
* Desc: Returns a pointer to a filled-in struct with informations.
* Repeated calls to this function will return a new struct each
* time, until a special "end of msgs" struct is returned as a signal
* that there is no more to get at this point.
* curl_multi_info_close() should be called when the last info has
* been read. In fact, it must be called if curl_multi_info_open()
* was called.
* The data the returned pointer points to will not survive calling
* The 'CURLMsg' struct is meant to be very simple and only contain
* very basic informations. If more involved information is wanted,
* we will provide the particular "transfer handle" in that struct
* and that should/could/would be used in subsequent
* curl_easy_getinfo() calls (or similar). The point being that we
* must never expose complex structs to applications, as then we'll
* undoubtably get backwards compatibility problems in the future.
* Name: curl_multi_info_read()
* Returns: A pointer to a struct, or NULL if it failed or ran out of structs.
* Note that if you continue reading until you get a NULL, you did
* read at least one too many times!
CURLMsg *curl_multi_info_read(CURLMinfo *info_handle);
* Desc: Terminates an info reading "session".
* Name: curl_multi_info_close()
* Returns: When we've read all the info we want from the info_handle, we
* signal this to the multi system by calling this function.
* After this call, the info_handle can no longer be used.
void curl_multi_info_close(CURLMinfo *info_handle);
-- Daniel Stenberg -- curl groks URLs -- http://curl.haxx.se/Received on 2001-11-03