| .\" ************************************************************************** |
| .\" * _ _ ____ _ |
| .\" * Project ___| | | | _ \| | |
| .\" * / __| | | | |_) | | |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| .\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. |
| .\" * |
| .\" * This software is licensed as described in the file COPYING, which |
| .\" * you should have received as part of this distribution. The terms |
| .\" * are also available at https://curl.se/docs/copyright.html. |
| .\" * |
| .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
| .\" * copies of the Software, and permit persons to whom the Software is |
| .\" * furnished to do so, under the terms of the COPYING file. |
| .\" * |
| .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
| .\" * KIND, either express or implied. |
| .\" * |
| .\" * SPDX-License-Identifier: curl |
| .\" * |
| .\" ************************************************************************** |
| .TH curl_multi_info_read 3 "18 Dec 2004" "libcurl" "libcurl" |
| .SH NAME |
| curl_multi_info_read - read multi stack information |
| .SH SYNOPSIS |
| .nf |
| #include <curl/curl.h> |
| |
| CURLMsg *curl_multi_info_read(CURLM *multi_handle, int *msgs_in_queue); |
| .fi |
| .SH 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 will return 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 \fImsgs_in_queue\fP will contain 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 will not return the same message |
| again. It will instead return new messages at each new invoke until the queue |
| is emptied. |
| |
| \fBWARNING:\fP The data the returned pointer points to will not survive |
| calling \fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or |
| \fIcurl_easy_cleanup(3)\fP. |
| |
| The \fICURLMsg\fP 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 |
| \fIcurl_easy_getinfo(3)\fP calls (or similar): |
| |
| .nf |
| 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; |
| }; |
| .fi |
| When \fBmsg\fP is \fICURLMSG_DONE\fP, the message identifies a transfer that |
| is done, and then \fBresult\fP contains the return code for the easy handle |
| that just completed. |
| |
| At this point, there are no other \fBmsg\fP types defined. |
| .SH EXAMPLE |
| .nf |
| 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_handle, &msgq); |
| if(m && (m->msg == CURLMSG_DONE)) { |
| CURL *e = m->easy_handle; |
| transfers--; |
| curl_multi_remove_handle(multi_handle, e); |
| curl_easy_cleanup(e); |
| } |
| } while(m); |
| .fi |
| .SH AVAILABILITY |
| Added in 7.9.6 |
| .SH 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. |
| .SH "SEE ALSO" |
| .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " curl_multi_perform "(3)" |