3
/*****************************************************************************
5
* Project ___| | | | _ \| |
7
* | (__| |_| | _ <| |___
8
* \___|\___/|_| \_\_____|
10
* Copyright (C) 2001, Daniel Stenberg, <daniel@haxx.se>, et al.
12
* In order to be useful for every potential user, curl and libcurl are
13
* dual-licensed under the MPL and the MIT/X-derivate licenses.
15
* You may opt to use, copy, modify, merge, publish, distribute and/or sell
16
* copies of the Software, and permit persons to whom the Software is
17
* furnished to do so, under the terms of the MPL or the MIT/X-derivate
18
* licenses. You may pick one of these licenses.
20
* This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
21
* KIND, either express or implied.
23
* $Id: multi.h,v 1.9 2002/02/25 10:12:04 bagder Exp $
24
*****************************************************************************/
26
This is meant to be the "external" header file. Don't give away any
29
This document presents a mixture of ideas from at least:
35
-------------------------------------------
38
o Enable a "pull" interface. The application that uses libcurl decides where
39
and when to ask libcurl to get/send data.
41
o Enable multiple simultaneous transfers in the same thread without making it
42
complicated for the application.
44
o Enable the application to select() on its own file descriptors and curl's
45
file descriptors simultaneous easily.
47
Example sources using this interface is here: ../multi/
50
#ifdef HAVE_SYS_SOCKET_H
51
#include <sys/socket.h>
53
#if defined(WIN32) && !defined(__GNUC__) || defined(__MINGW32__)
57
#include <curl/curl.h>
62
CURLM_CALL_MULTI_PERFORM=-1, /* please call curl_multi_perform() soon */
64
CURLM_BAD_HANDLE, /* the passed-in handle is not a valid CURLM handle */
65
CURLM_BAD_EASY_HANDLE, /* an easy handle was not good/valid */
66
CURLM_OUT_OF_MEMORY, /* if you ever get this, you're in deep sh*t */
67
CURLM_INTERNAL_ERROR, /* this is a libcurl bug */
72
CURLMSG_NONE, /* first, not used */
73
CURLMSG_DONE, /* This easy handle has completed. 'whatever' points to
74
the CURLcode of the transfer */
75
CURLMSG_LAST /* last, not used */
79
CURLMSG msg; /* what this message means */
80
CURL *easy_handle; /* the handle it concerns */
82
void *whatever; /* message-specific data */
83
CURLcode result; /* return code for transfer */
86
typedef struct CURLMsg CURLMsg;
89
* Name: curl_multi_init()
91
* Desc: inititalize multi-style curl usage
92
* Returns: a new CURLM handle to use in all 'curl_multi' functions.
94
CURLM *curl_multi_init(void);
97
* Name: curl_multi_add_handle()
99
* Desc: add a standard curl handle to the multi stack
100
* Returns: CURLMcode type, general multi error code.
102
CURLMcode curl_multi_add_handle(CURLM *multi_handle,
106
* Name: curl_multi_remove_handle()
108
* Desc: removes a curl handle from the multi stack again
109
* Returns: CURLMcode type, general multi error code.
111
CURLMcode curl_multi_remove_handle(CURLM *multi_handle,
115
* Name: curl_multi_fdset()
117
* Desc: Ask curl for its fd_set sets. The app can use these to select() or
118
* poll() on. We want curl_multi_perform() called as soon as one of
120
* Returns: CURLMcode type, general multi error code.
122
CURLMcode curl_multi_fdset(CURLM *multi_handle,
124
fd_set *write_fd_set,
129
* Name: curl_multi_perform()
131
* Desc: When the app thinks there's data available for curl it calls this
132
* function to read/write whatever there is right now. This returns
133
* as soon as the reads and writes are done. This function does not
134
* require that there actually is data available for reading or that
135
* data can be written, it can be called just in case. It returns
136
* the number of handles that still transfer data in the second
137
* argument's integer-pointer.
139
* Returns: CURLMcode type, general multi error code. *NOTE* that this only
140
* returns errors etc regarding the whole multi stack. There might
141
* still have occurred problems on invidual transfers even when this
144
CURLMcode curl_multi_perform(CURLM *multi_handle,
145
int *running_handles);
148
* Name: curl_multi_cleanup()
150
* Desc: Cleans up and removes a whole multi stack. It does not free or
151
* touch any individual easy handles in any way. We need to define
152
* in what state those handles will be if this function is called
153
* in the middle of a transfer.
154
* Returns: CURLMcode type, general multi error code.
156
CURLMcode curl_multi_cleanup(CURLM *multi_handle);
159
* Name: curl_multi_info_read()
161
* Desc: Ask the multi handle if there's any messages/informationals from
162
* the individual transfers. Messages include informationals such as
163
* error code from the transfer or just the fact that a transfer is
164
* completed. More details on these should be written down as well.
166
* Repeated calls to this function will return a new struct each
167
* time, until a special "end of msgs" struct is returned as a signal
168
* that there is no more to get at this point.
170
* The data the returned pointer points to will not survive calling
171
* curl_multi_cleanup().
173
* The 'CURLMsg' struct is meant to be very simple and only contain
174
* very basic informations. If more involved information is wanted,
175
* we will provide the particular "transfer handle" in that struct
176
* and that should/could/would be used in subsequent
177
* curl_easy_getinfo() calls (or similar). The point being that we
178
* must never expose complex structs to applications, as then we'll
179
* undoubtably get backwards compatibility problems in the future.
181
* Returns: A pointer to a filled-in struct, or NULL if it failed or ran out
182
* of structs. It also writes the number of messages left in the
183
* queue (after this read) in the integer the second argument points
186
CURLMsg *curl_multi_info_read(CURLM *multi_handle,
added
removed
lib/multi.h
