XFERINFOFUNCTION: Description of return values is confusing

[Benjamin-Riefenstahl-mecom]

Specify which documentation you found a problem with

The documentation for CURLOPT_XFERINFOFUNCTION and CURLOPT_PROGRESSFUNCTION says:

If your callback function returns CURL_PROGRESSFUNC_CONTINUE it makes libcurl to continue executing the default progress function.

Returning any other non-zero value from this callback makes libcurl abort the transfer and return CURLE_ABORTED_BY_CALLBACK.

The problem

It is only implied, but not made explicit, that the usual return value is 0. It is also not clear which actual values are valid to cause an abort, because the value for CURL_PROGRESSFUNC_CONTINUE is not documented. I currently use min(-42, CURL_PROGRESSFUNC_CONTINUE - 42); but that seems rather clumsy.

I suggest:

If your callback function returns CURL_PROGRESSFUNC_CONTINUE (<actual value here>) it makes libcurl execute the default progress function and than continue the transfer. If it returns CURL_PROGRESSFUNC_OK (0) the default progress function is not executed and the transfer is continued. If it returns CURL_PROGRESSFUNC_ABORT (-1) or any other value the default progress function is not executed, the transfer is aborted and transfer function will return CURLE_ABORTED_BY_CALLBACK.

This assumes of course that the constants CURL_PROGRESSFUNC_OK and CURL_PROGRESSFUNC_ABORT are actually defined in the headers.

[Benjamin-Riefenstahl-mecom]

Thanks, this works for me.