diff options
Diffstat (limited to 'docs/libcurl/curl_multi_info_read.md')
-rw-r--r-- | docs/libcurl/curl_multi_info_read.md | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/docs/libcurl/curl_multi_info_read.md b/docs/libcurl/curl_multi_info_read.md new file mode 100644 index 000000000..23d515d8f --- /dev/null +++ b/docs/libcurl/curl_multi_info_read.md @@ -0,0 +1,102 @@ +--- +c: Copyright (C) Daniel Stenberg, <daniel.se>, et al. +SPDX-License-Identifier: curl +Title: curl_multi_info_read +Section: 3 +Source: libcurl +See-also: + - curl_multi_cleanup (3) + - curl_multi_init (3) + - curl_multi_perform (3) +--- + +# NAME + +curl_multi_info_read - read multi stack information + +# SYNOPSIS + +~~~c +#include <curl/curl.h> + +CURLMsg *curl_multi_info_read(CURLM *multi_handle, int *msgs_in_queue); +~~~ + +# DESCRIPTION + +Ask the multi handle if there are any messages from the individual +transfers. Messages may include information such as an error code from the +transfer or just the fact that a transfer is completed. More details on these +should be written down as well. + +Repeated calls to this function returns a new struct each time, until a NULL +is returned as a signal that there is no more to get at this point. The +integer pointed to with *msgs_in_queue* contains the number of remaining +messages after this function was called. + +When you fetch a message using this function, it is removed from the internal +queue so calling this function again does not return the same message +again. It instead returns new messages at each new invoke until the queue is +emptied. + +**WARNING:** The data the returned pointer points to does not survive +calling curl_multi_cleanup(3), curl_multi_remove_handle(3) or +curl_easy_cleanup(3). + +The *CURLMsg* struct is simple and only contains basic information. If +more involved information is wanted, the particular "easy handle" is present +in that struct and can be used in subsequent regular +curl_easy_getinfo(3) calls (or similar): + +~~~c + struct CURLMsg { + CURLMSG msg; /* what this message means */ + CURL *easy_handle; /* the handle it concerns */ + union { + void *whatever; /* message-specific data */ + CURLcode result; /* return code for transfer */ + } data; + }; +~~~ +When **msg** is *CURLMSG_DONE*, the message identifies a transfer that +is done, and then **result** contains the return code for the easy handle +that just completed. + +At this point, there are no other **msg** types defined. + +# EXAMPLE + +~~~c +int main(void) +{ + CURLM *multi = curl_multi_init(); + CURL *curl = curl_easy_init(); + if(curl) { + struct CURLMsg *m; + + /* call curl_multi_perform or curl_multi_socket_action first, then loop + through and check if there are any transfers that have completed */ + + do { + int msgq = 0; + m = curl_multi_info_read(multi, &msgq); + if(m && (m->msg == CURLMSG_DONE)) { + CURL *e = m->easy_handle; + /* m->data.result holds the error code for the transfer */ + curl_multi_remove_handle(multi, e); + curl_easy_cleanup(e); + } + } while(m); + } +} +~~~ + +# AVAILABILITY + +Added in 7.9.6 + +# RETURN VALUE + +A pointer to a filled-in struct, or NULL if it failed or ran out of +structs. It also writes the number of messages left in the queue (after this +read) in the integer the second argument points to. |