cURL / Mailing Lists / curl-library / Single Mail


Re: the new 'multi' API

From: Daniel Stenberg <>
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
 * curl_multi_cleanup().
 * 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 --
Received on 2001-11-03