<ahref="multi_8h.html">Go to the documentation of this file.</a><divclass="fragment"><divclass="line"><aname="l00001"></a><spanclass="lineno"> 1</span> <spanclass="preprocessor">#ifndef __CURL_MULTI_H</span></div>
<divclass="line"><aname="l00012"></a><spanclass="lineno"> 12</span> <spanclass="comment"> * This software is licensed as described in the file COPYING, which</span></div>
<divclass="line"><aname="l00013"></a><spanclass="lineno"> 13</span> <spanclass="comment"> * you should have received as part of this distribution. The terms</span></div>
<divclass="line"><aname="l00014"></a><spanclass="lineno"> 14</span> <spanclass="comment"> * are also available at http://curl.haxx.se/docs/copyright.html.</span></div>
<divclass="line"><aname="l00016"></a><spanclass="lineno"> 16</span> <spanclass="comment"> * You may opt to use, copy, modify, merge, publish, distribute and/or sell</span></div>
<divclass="line"><aname="l00017"></a><spanclass="lineno"> 17</span> <spanclass="comment"> * copies of the Software, and permit persons to whom the Software is</span></div>
<divclass="line"><aname="l00018"></a><spanclass="lineno"> 18</span> <spanclass="comment"> * furnished to do so, under the terms of the COPYING file.</span></div>
<divclass="line"><aname="l00020"></a><spanclass="lineno"> 20</span> <spanclass="comment"> * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY</span></div>
<divclass="line"><aname="l00021"></a><spanclass="lineno"> 21</span> <spanclass="comment"> * KIND, either express or implied.</span></div>
<divclass="line"><aname="l00025"></a><spanclass="lineno"> 25</span> <spanclass="comment"> This is an "external" header file. Don't give away any internals here!</span></div>
<divclass="line"><aname="l00029"></a><spanclass="lineno"> 29</span> <spanclass="comment"> o Enable a "pull" interface. The application that uses libcurl decides where</span></div>
<divclass="line"><aname="l00030"></a><spanclass="lineno"> 30</span> <spanclass="comment"> and when to ask libcurl to get/send data.</span></div>
<divclass="line"><aname="l00032"></a><spanclass="lineno"> 32</span> <spanclass="comment"> o Enable multiple simultaneous transfers in the same thread without making it</span></div>
<divclass="line"><aname="l00033"></a><spanclass="lineno"> 33</span> <spanclass="comment"> complicated for the application.</span></div>
<divclass="line"><aname="l00035"></a><spanclass="lineno"> 35</span> <spanclass="comment"> o Enable the application to select() on its own file descriptors and curl's</span></div>
<divclass="line"><aname="l00041"></a><spanclass="lineno"> 41</span> <spanclass="comment"> * This header file should not really need to include "curl.h" since curl.h</span></div>
<divclass="line"><aname="l00042"></a><spanclass="lineno"> 42</span> <spanclass="comment"> * itself includes this file and we expect user applications to do #include</span></div>
<divclass="line"><aname="l00043"></a><spanclass="lineno"> 43</span> <spanclass="comment"> * <curl/curl.h> without the need for especially including multi.h.</span></div>
<divclass="line"><aname="l00045"></a><spanclass="lineno"> 45</span> <spanclass="comment"> * For some reason we added this include here at one point, and rather than to</span></div>
<divclass="line"><aname="l00046"></a><spanclass="lineno"> 46</span> <spanclass="comment"> * break existing (wrongly written) libcurl applications, we leave it as-is</span></div>
<divclass="line"><aname="l00047"></a><spanclass="lineno"> 47</span> <spanclass="comment"> * but with this warning attached.</span></div>
<divclass="line"><aname="l00061"></a><spanclass="lineno"><aclass="line"href="multi_8h.html#a92acc8d3a23eaae72955b8a8b22c83e3a8876b8ad10b9b2e9ee4cfb22034803ed"> 61</a></span> <aclass="code"href="multi_8h.html#a92acc8d3a23eaae72955b8a8b22c83e3a8876b8ad10b9b2e9ee4cfb22034803ed">CURLM_BAD_HANDLE</a>, <spanclass="comment">/* the passed-in handle is not a valid CURLM handle */</span></div>
<divclass="line"><aname="l00062"></a><spanclass="lineno"><aclass="line"href="multi_8h.html#a92acc8d3a23eaae72955b8a8b22c83e3af6c791401114f6d764dbb8209838ba31"> 62</a></span> <aclass="code"href="multi_8h.html#a92acc8d3a23eaae72955b8a8b22c83e3af6c791401114f6d764dbb8209838ba31">CURLM_BAD_EASY_HANDLE</a>, <spanclass="comment">/* an easy handle was not good/valid */</span></div>
<divclass="line"><aname="l00063"></a><spanclass="lineno"><aclass="line"href="multi_8h.html#a92acc8d3a23eaae72955b8a8b22c83e3a323be072bc47b2a7ff1d3fc4533e8f70"> 63</a></span> <aclass="code"href="multi_8h.html#a92acc8d3a23eaae72955b8a8b22c83e3a323be072bc47b2a7ff1d3fc4533e8f70">CURLM_OUT_OF_MEMORY</a>, <spanclass="comment">/* if you ever get this, you're in deep sh*t */</span></div>
<divclass="line"><aname="l00064"></a><spanclass="lineno"><aclass="line"href="multi_8h.html#a92acc8d3a23eaae72955b8a8b22c83e3a53d037bdcf6900341e9f83efbf14b1d1"> 64</a></span> <aclass="code"href="multi_8h.html#a92acc8d3a23eaae72955b8a8b22c83e3a53d037bdcf6900341e9f83efbf14b1d1">CURLM_INTERNAL_ERROR</a>, <spanclass="comment">/* this is a libcurl bug */</span></div>
<divclass="line"><aname="l00065"></a><spanclass="lineno"><aclass="line"href="multi_8h.html#a92acc8d3a23eaae72955b8a8b22c83e3a13188cf491bdb9a8f77a5bed6365c34c"> 65</a></span> <aclass="code"href="multi_8h.html#a92acc8d3a23eaae72955b8a8b22c83e3a13188cf491bdb9a8f77a5bed6365c34c">CURLM_BAD_SOCKET</a>, <spanclass="comment">/* the passed in socket argument did not match */</span></div>
<divclass="line"><aname="l00066"></a><spanclass="lineno"><aclass="line"href="multi_8h.html#a92acc8d3a23eaae72955b8a8b22c83e3afeaa68ddf000332d41ce915f8658cf4c"> 66</a></span> <aclass="code"href="multi_8h.html#a92acc8d3a23eaae72955b8a8b22c83e3afeaa68ddf000332d41ce915f8658cf4c">CURLM_UNKNOWN_OPTION</a>, <spanclass="comment">/* curl_multi_setopt() with unsupported option */</span></div>
<divclass="line"><aname="l00070"></a><spanclass="lineno"> 70</span> <spanclass="comment">/* just to make code nicer when using curl_multi_socket() you can now check</span></div>
<divclass="line"><aname="l00071"></a><spanclass="lineno"> 71</span> <spanclass="comment"> for CURLM_CALL_MULTI_SOCKET too in the same style it works for</span></div>
<divclass="line"><aname="l00072"></a><spanclass="lineno"> 72</span> <spanclass="comment"> curl_multi_perform() and CURLM_CALL_MULTI_PERFORM */</span></div>
<divclass="line"><aname="l00076"></a><spanclass="lineno"><aclass="line"href="multi_8h.html#a7f87d375fc82f79b121ef4adaeedc154ae3b4bbc61ade639e930424147049e4e5"> 76</a></span> <aclass="code"href="multi_8h.html#a7f87d375fc82f79b121ef4adaeedc154ae3b4bbc61ade639e930424147049e4e5">CURLMSG_NONE</a>, <spanclass="comment">/* first, not used */</span></div>
<divclass="line"><aname="l00077"></a><spanclass="lineno"><aclass="line"href="multi_8h.html#a7f87d375fc82f79b121ef4adaeedc154a374efd706ae91c3321d6360be3c398b7"> 77</a></span> <aclass="code"href="multi_8h.html#a7f87d375fc82f79b121ef4adaeedc154a374efd706ae91c3321d6360be3c398b7">CURLMSG_DONE</a>, <spanclass="comment">/* This easy handle has completed. 'result' contains</span></div>
<divclass="line"><aname="l00078"></a><spanclass="lineno"> 78</span> <spanclass="comment"> the CURLcode of the transfer */</span></div>
<divclass="line"><aname="l00079"></a><spanclass="lineno"><aclass="line"href="multi_8h.html#a7f87d375fc82f79b121ef4adaeedc154a57d9664397bd951b89bf317b7f4721ec"> 79</a></span> <aclass="code"href="multi_8h.html#a7f87d375fc82f79b121ef4adaeedc154a57d9664397bd951b89bf317b7f4721ec">CURLMSG_LAST</a><spanclass="comment">/* last, not used */</span></div>
<divclass="line"><aname="l00083"></a><spanclass="lineno"><aclass="line"href="multi_8h.html#ab6671c39e641443bbcc384008275ed66"> 83</a></span> <aclass="code"href="multi_8h.html#a7f87d375fc82f79b121ef4adaeedc154">CURLMSG</a><aclass="code"href="multi_8h.html#ab6671c39e641443bbcc384008275ed66">msg</a>; <spanclass="comment">/* what this message means */</span></div>
<divclass="line"><aname="l00084"></a><spanclass="lineno"><aclass="line"href="multi_8h.html#a5000cbf12257367f7ae2773a26ff4483"> 84</a></span> <aclass="code"href="curl_8h.html#ace655e3633b6533591283994d6b5cdda">CURL</a> *<aclass="code"href="multi_8h.html#a5000cbf12257367f7ae2773a26ff4483">easy_handle</a>; <spanclass="comment">/* the handle it concerns */</span></div>
<divclass="line"><aname="l00086"></a><spanclass="lineno"> 86</span> <spanclass="keywordtype">void</span> *whatever; <spanclass="comment">/* message-specific data */</span></div>
<divclass="line"><aname="l00087"></a><spanclass="lineno"> 87</span> <aclass="code"href="curl_8h.html#af0691941698240652e0a391394217951">CURLcode</a> result; <spanclass="comment">/* return code for transfer */</span></div>
<divclass="line"><aname="l00097"></a><spanclass="lineno"> 97</span> <spanclass="comment"> * Returns: a new CURLM handle to use in all 'curl_multi' functions.</span></div>
<divclass="line"><aname="l00104"></a><spanclass="lineno"> 104</span> <spanclass="comment"> * Desc: add a standard curl handle to the multi stack</span></div>
<divclass="line"><aname="l00106"></a><spanclass="lineno"> 106</span> <spanclass="comment"> * Returns: CURLMcode type, general multi error code.</span></div>
<divclass="line"><aname="l00114"></a><spanclass="lineno"> 114</span> <spanclass="comment"> * Desc: removes a curl handle from the multi stack again</span></div>
<divclass="line"><aname="l00116"></a><spanclass="lineno"> 116</span> <spanclass="comment"> * Returns: CURLMcode type, general multi error code.</span></div>
<divclass="line"><aname="l00124"></a><spanclass="lineno"> 124</span> <spanclass="comment"> * Desc: Ask curl for its fd_set sets. The app can use these to select() or</span></div>
<divclass="line"><aname="l00125"></a><spanclass="lineno"> 125</span> <spanclass="comment"> * poll() on. We want curl_multi_perform() called as soon as one of</span></div>
<divclass="line"><aname="l00126"></a><spanclass="lineno"> 126</span> <spanclass="comment"> * them are ready.</span></div>
<divclass="line"><aname="l00128"></a><spanclass="lineno"> 128</span> <spanclass="comment"> * Returns: CURLMcode type, general multi error code.</span></div>
<divclass="line"><aname="l00139"></a><spanclass="lineno"> 139</span> <spanclass="comment"> * Desc: When the app thinks there's data available for curl it calls this</span></div>
<divclass="line"><aname="l00140"></a><spanclass="lineno"> 140</span> <spanclass="comment"> * function to read/write whatever there is right now. This returns</span></div>
<divclass="line"><aname="l00141"></a><spanclass="lineno"> 141</span> <spanclass="comment"> * as soon as the reads and writes are done. This function does not</span></div>
<divclass="line"><aname="l00142"></a><spanclass="lineno"> 142</span> <spanclass="comment"> * require that there actually is data available for reading or that</span></div>
<divclass="line"><aname="l00143"></a><spanclass="lineno"> 143</span> <spanclass="comment"> * data can be written, it can be called just in case. It returns</span></div>
<divclass="line"><aname="l00144"></a><spanclass="lineno"> 144</span> <spanclass="comment"> * the number of handles that still transfer data in the second</span></div>
<divclass="line"><aname="l00147"></a><spanclass="lineno"> 147</span> <spanclass="comment"> * Returns: CURLMcode type, general multi error code. *NOTE* that this only</span></div>
<divclass="line"><aname="l00148"></a><spanclass="lineno"> 148</span> <spanclass="comment"> * returns errors etc regarding the whole multi stack. There might</span></div>
<divclass="line"><aname="l00149"></a><spanclass="lineno"> 149</span> <spanclass="comment"> * still have occurred problems on invidual transfers even when this</span></div>
<divclass="line"><aname="l00158"></a><spanclass="lineno"> 158</span> <spanclass="comment"> * Desc: Cleans up and removes a whole multi stack. It does not free or</span></div>
<divclass="line"><aname="l00159"></a><spanclass="lineno"> 159</span> <spanclass="comment"> * touch any individual easy handles in any way. We need to define</span></div>
<divclass="line"><aname="l00160"></a><spanclass="lineno"> 160</span> <spanclass="comment"> * in what state those handles will be if this function is called</span></div>
<divclass="line"><aname="l00161"></a><spanclass="lineno"> 161</span> <spanclass="comment"> * in the middle of a transfer.</span></div>
<divclass="line"><aname="l00163"></a><spanclass="lineno"> 163</span> <spanclass="comment"> * Returns: CURLMcode type, general multi error code.</span></div>
<divclass="line"><aname="l00170"></a><spanclass="lineno"> 170</span> <spanclass="comment"> * Desc: Ask the multi handle if there's any messages/informationals from</span></div>
<divclass="line"><aname="l00171"></a><spanclass="lineno"> 171</span> <spanclass="comment"> * the individual transfers. Messages include informationals such as</span></div>
<divclass="line"><aname="l00172"></a><spanclass="lineno"> 172</span> <spanclass="comment"> * error code from the transfer or just the fact that a transfer is</span></div>
<divclass="line"><aname="l00173"></a><spanclass="lineno"> 173</span> <spanclass="comment"> * completed. More details on these should be written down as well.</span></div>
<divclass="line"><aname="l00175"></a><spanclass="lineno"> 175</span> <spanclass="comment"> * Repeated calls to this function will return a new struct each</span></div>
<divclass="line"><aname="l00176"></a><spanclass="lineno"> 176</span> <spanclass="comment"> * time, until a special "end of msgs" struct is returned as a signal</span></div>
<divclass="line"><aname="l00177"></a><spanclass="lineno"> 177</span> <spanclass="comment"> * that there is no more to get at this point.</span></div>
<divclass="line"><aname="l00179"></a><spanclass="lineno"> 179</span> <spanclass="comment"> * The data the returned pointer points to will not survive calling</span></div>
<divclass="line"><aname="l00182"></a><spanclass="lineno"> 182</span> <spanclass="comment"> * The 'CURLMsg' struct is meant to be very simple and only contain</span></div>
<divclass="line"><aname="l00183"></a><spanclass="lineno"> 183</span> <spanclass="comment"> * very basic informations. If more involved information is wanted,</span></div>
<divclass="line"><aname="l00184"></a><spanclass="lineno"> 184</span> <spanclass="comment"> * we will provide the particular "transfer handle" in that struct</span></div>
<divclass="line"><aname="l00185"></a><spanclass="lineno"> 185</span> <spanclass="comment"> * and that should/could/would be used in subsequent</span></div>
<divclass="line"><aname="l00186"></a><spanclass="lineno"> 186</span> <spanclass="comment"> * curl_easy_getinfo() calls (or similar). The point being that we</span></div>
<divclass="line"><aname="l00187"></a><spanclass="lineno"> 187</span> <spanclass="comment"> * must never expose complex structs to applications, as then we'll</span></div>
<divclass="line"><aname="l00188"></a><spanclass="lineno"> 188</span> <spanclass="comment"> * undoubtably get backwards compatibility problems in the future.</span></div>
<divclass="line"><aname="l00190"></a><spanclass="lineno"> 190</span> <spanclass="comment"> * Returns: A pointer to a filled-in struct, or NULL if it failed or ran out</span></div>
<divclass="line"><aname="l00191"></a><spanclass="lineno"> 191</span> <spanclass="comment"> * of structs. It also writes the number of messages left in the</span></div>
<divclass="line"><aname="l00192"></a><spanclass="lineno"> 192</span> <spanclass="comment"> * queue (after this read) in the integer the second argument points</span></div>
<divclass="line"><aname="l00201"></a><spanclass="lineno"> 201</span> <spanclass="comment"> * Desc: The curl_multi_strerror function may be used to turn a CURLMcode</span></div>
<divclass="line"><aname="l00202"></a><spanclass="lineno"> 202</span> <spanclass="comment"> * value into the equivalent human readable error string. This is</span></div>
<divclass="line"><aname="l00203"></a><spanclass="lineno"> 203</span> <spanclass="comment"> * useful for printing meaningful error messages.</span></div>
<divclass="line"><aname="l00205"></a><spanclass="lineno"> 205</span> <spanclass="comment"> * Returns: A pointer to a zero-terminated error message.</span></div>
<divclass="line"><aname="l00213"></a><spanclass="lineno"> 213</span> <spanclass="comment"> * Desc: An alternative version of curl_multi_perform() that allows the</span></div>
<divclass="line"><aname="l00214"></a><spanclass="lineno"> 214</span> <spanclass="comment"> * application to pass in one of the file descriptors that have been</span></div>
<divclass="line"><aname="l00215"></a><spanclass="lineno"> 215</span> <spanclass="comment"> * detected to have "action" on them and let libcurl perform.</span></div>
<divclass="line"><aname="l00216"></a><spanclass="lineno"> 216</span> <spanclass="comment"> * See man page for details.</span></div>
<divclass="line"><aname="l00240"></a><spanclass="lineno"> 240</span> <spanclass="comment"> * Desc: Called by libcurl whenever the library detects a change in the</span></div>
<divclass="line"><aname="l00241"></a><spanclass="lineno"> 241</span> <spanclass="comment"> * maximum number of milliseconds the app is allowed to wait before</span></div>
<divclass="line"><aname="l00242"></a><spanclass="lineno"> 242</span> <spanclass="comment"> * curl_multi_socket() or curl_multi_perform() must be called</span></div>
<divclass="line"><aname="l00243"></a><spanclass="lineno"> 243</span> <spanclass="comment"> * (to allow libcurl's timed events to take place).</span></div>
<divclass="line"><aname="l00245"></a><spanclass="lineno"> 245</span> <spanclass="comment"> * Returns: The callback should return zero.</span></div>
<divclass="line"><aname="l00247"></a><spanclass="lineno"><aclass="line"href="multi_8h.html#a18a7e76c1666503b960dfdfa3cf9843f"> 247</a></span> <spanclass="keyword">typedef</span> int (*<aclass="code"href="multi_8h.html#a18a7e76c1666503b960dfdfa3cf9843f">curl_multi_timer_callback</a>)(<aclass="code"href="multi_8h.html#a5ad3a82c3de54ee92ce4ddb052d18036">CURLM</a> *multi, <spanclass="comment">/* multi handle */</span></div>
<divclass="line"><aname="l00248"></a><spanclass="lineno"> 248</span> <spanclass="keywordtype">long</span> timeout_ms, <spanclass="comment">/* see above */</span></div>
<divclass="line"><aname="l00264"></a><spanclass="lineno"> 264</span> <spanclass="comment">/* This macro below was added in 7.16.3 to push users who recompile to use</span></div>
<divclass="line"><aname="l00265"></a><spanclass="lineno"> 265</span> <spanclass="comment"> the new curl_multi_socket_action() instead of the old curl_multi_socket()</span></div>
<divclass="line"><aname="l00273"></a><spanclass="lineno"> 273</span> <spanclass="comment"> * Desc: Returns the maximum number of milliseconds the app is allowed to</span></div>
<divclass="line"><aname="l00274"></a><spanclass="lineno"> 274</span> <spanclass="comment"> * wait before curl_multi_socket() or curl_multi_perform() must be</span></div>
<divclass="line"><aname="l00275"></a><spanclass="lineno"> 275</span> <spanclass="comment"> * called (to allow libcurl's timed events to take place).</span></div>
<divclass="line"><aname="l00282"></a><spanclass="lineno"> 282</span> <spanclass="preprocessor">#undef CINIT </span><spanclass="comment">/* re-using the same name as in curl.h */</span><spanclass="preprocessor"></span></div>
<divclass="line"><aname="l00287"></a><spanclass="lineno"> 287</span> <spanclass="comment">/* The macro "##" is ISO C, we assume pre-ISO C doesn't support it. */</span></div>
<divclass="line"><aname="l00288"></a><spanclass="lineno"> 288</span> <spanclass="preprocessor">#define LONG CURLOPTTYPE_LONG</span></div>
<divclass="line"><aname="l00296"></a><spanclass="lineno"> 296</span> <spanclass="comment">/* This is the socket callback function pointer */</span></div>
<divclass="line"><aname="l00299"></a><spanclass="lineno"> 299</span> <spanclass="comment">/* This is the argument passed to the socket callback */</span></div>
<divclass="line"><aname="l00302"></a><spanclass="lineno"> 302</span> <spanclass="comment">/* set to 1 to enable pipelining for this multi handle */</span></div>
<divclass="line"><aname="l00305"></a><spanclass="lineno"> 305</span> <spanclass="comment">/* This is the timer callback function pointer */</span></div>
<divclass="line"><aname="l00308"></a><spanclass="lineno"> 308</span> <spanclass="comment">/* This is the argument passed to the timer callback */</span></div>
<divclass="line"><aname="l00311"></a><spanclass="lineno"> 311</span> <spanclass="comment">/* maximum number of entries in the connection cache */</span></div>
<divclass="line"><aname="l00314"></a><spanclass="lineno"><aclass="line"href="multi_8h.html#a63d84039b5e6092edec1f44c87dd1fe5a8b9faed3bc4162b20ab14f775a3ddb88"> 314</a></span> <aclass="code"href="multi_8h.html#a63d84039b5e6092edec1f44c87dd1fe5a8b9faed3bc4162b20ab14f775a3ddb88">CURLMOPT_LASTENTRY</a><spanclass="comment">/* the last unused */</span></div>
<divclass="line"><aname="l00321"></a><spanclass="lineno"> 321</span> <spanclass="comment"> * Desc: Sets options for the multi handle.</span></div>
<divclass="line"><aname="l00332"></a><spanclass="lineno"> 332</span> <spanclass="comment"> * Desc: This function sets an association in the multi handle between the</span></div>
<divclass="line"><aname="l00333"></a><spanclass="lineno"> 333</span> <spanclass="comment"> * given socket and a private pointer of the application. This is</span></div>
<divclass="line"><aname="l00334"></a><spanclass="lineno"> 334</span> <spanclass="comment"> * (only) useful for curl_multi_socket uses.</span></div>
<divclass="ttc"id="amulti_8h_html_aad2178147cea07493eba9b4da3fb27df"><divclass="ttname"><ahref="multi_8h.html#aad2178147cea07493eba9b4da3fb27df">curl_multi_socket</a></div><divclass="ttdeci">#define curl_multi_socket(x, y, z)</div><divclass="ttdef"><b>Definition:</b><ahref="multi_8h_source.html#l00267">multi.h:267</a></div></div>
<divclass="ttc"id="amulti_8h_html_a4dd175dae1779c2984f366deffcc99cf"><divclass="ttname"><ahref="multi_8h.html#a4dd175dae1779c2984f366deffcc99cf">curl_multi_socket_action</a></div><divclass="ttdeci">CURL_EXTERN CURLMcode curl_multi_socket_action(CURLM *multi_handle, curl_socket_t s, int ev_bitmask, int *running_handles)</div></div>
