Return to curl_multi_info_read.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl

Annotation of embedaddon/curl/docs/libcurl/curl_multi_info_read.3, revision 1.1.1.1

1.1       misho       1: .\" **************************************************************************
                      2: .\" *                                  _   _ ____  _
                      3: .\" *  Project                     ___| | | |  _ \| |
                      4: .\" *                             / __| | | | |_) | |
                      5: .\" *                            | (__| |_| |  _ <| |___
                      6: .\" *                             \___|\___/|_| \_\_____|
                      7: .\" *
                      8: .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
                      9: .\" *
                     10: .\" * This software is licensed as described in the file COPYING, which
                     11: .\" * you should have received as part of this distribution. The terms
                     12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
                     13: .\" *
                     14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
                     15: .\" * copies of the Software, and permit persons to whom the Software is
                     16: .\" * furnished to do so, under the terms of the COPYING file.
                     17: .\" *
                     18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
                     19: .\" * KIND, either express or implied.
                     20: .\" *
                     21: .\" **************************************************************************
                     22: .TH curl_multi_info_read 3 "March 23, 2020" "libcurl 7.70.0" "libcurl Manual"
                     23: 
                     24: .SH NAME
                     25: curl_multi_info_read - read multi stack informationals
                     26: .SH SYNOPSIS
                     27: #include <curl/curl.h>
                     28: 
                     29: CURLMsg *curl_multi_info_read( CURLM *multi_handle,
                     30:                                int *msgs_in_queue);
                     31: .ad
                     32: .SH DESCRIPTION
                     33: Ask the multi handle if there are any messages/informationals from the
                     34: individual transfers. Messages may include informationals such as an error
                     35: code from the transfer or just the fact that a transfer is completed. More
                     36: details on these should be written down as well.
                     37: 
                     38: Repeated calls to this function will return a new struct each time, until a
                     39: NULL is returned as a signal that there is no more to get at this point. The
                     40: integer pointed to with \fImsgs_in_queue\fP will contain the number of
                     41: remaining messages after this function was called.
                     42: 
                     43: When you fetch a message using this function, it is removed from the internal
                     44: queue so calling this function again will not return the same message
                     45: again. It will instead return new messages at each new invoke until the queue
                     46: is emptied.
                     47: 
                     48: \fBWARNING:\fP The data the returned pointer points to will not survive
                     49: calling \fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or
                     50: \fIcurl_easy_cleanup(3)\fP.
                     51: 
                     52: The 'CURLMsg' struct is very simple and only contains very basic information.
                     53: If more involved information is wanted, the particular "easy handle" is
                     54: present in that struct and can be used in subsequent regular
                     55: \fIcurl_easy_getinfo(3)\fP calls (or similar):
                     56: 
                     57: .nf
                     58:  struct CURLMsg {
                     59:    CURLMSG msg;       /* what this message means */
                     60:    CURL *easy_handle; /* the handle it concerns */
                     61:    union {
                     62:      void *whatever;    /* message-specific data */
                     63:      CURLcode result;   /* return code for transfer */
                     64:    } data;
                     65:  };
                     66: .fi
                     67: When \fBmsg\fP is \fICURLMSG_DONE\fP, the message identifies a transfer that
                     68: is done, and then \fBresult\fP contains the return code for the easy handle
                     69: that just completed.
                     70: 
                     71: At this point, there are no other \fBmsg\fP types defined.
                     72: .SH EXAMPLE
                     73: .nf
                     74: struct CURLMsg *m;
                     75: 
                     76: /* call curl_multi_perform or curl_multi_socket_action first, then loop
                     77:    through and check if there are any transfers that have completed */
                     78: 
                     79: do {
                     80:   int msgq = 0;
                     81:   m = curl_multi_info_read(multi_handle, &msgq);
                     82:   if(m && (m->msg == CURLMSG_DONE)) {
                     83:     CURL *e = m->easy_handle;
                     84:     transfers--;
                     85:     curl_multi_remove_handle(multi_handle, e);
                     86:     curl_easy_cleanup(e);
                     87:   }
                     88: } while(m);
                     89: .fi
                     90: .SH "RETURN VALUE"
                     91: A pointer to a filled-in struct, or NULL if it failed or ran out of
                     92: structs. It also writes the number of messages left in the queue (after this
                     93: read) in the integer the second argument points to.
                     94: .SH "SEE ALSO"
                     95: .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " curl_multi_perform "(3)"