108 lines
3.9 KiB
Groff
108 lines
3.9 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * 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 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 \fImsgs_in_queue\fP 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.
|
|
|
|
\fBWARNING:\fP The data the returned pointer points to does 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
|
|
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);
|
|
}
|
|
}
|
|
.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),
|
|
.BR curl_multi_init (3),
|
|
.BR curl_multi_perform (3)
|