romenskiy2012/curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-08-25 22:33:34 +03:00
Code Issues Projects Releases Packages Wiki Activity

Introducing curl_easy_pause() and new magic return codes for both the read

Browse source 
and the write callbacks that now can make a connection's reading and/or
writing get paused.
This commit is contained in:
Daniel Stenberg 2008-01-08 14:52:05 +00:00
parent 5e1c9e90d9
commit de23b98522
14 changed files with 358 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/curl.1
View file

@ -21,7 +21,7 @@
.\" * $Id$
.\" **************************************************************************
.\"
.TH curl 1 "5 Jan 2008" "Curl 7.17.2" "Curl Manual"
.TH curl 1 "5 Jan 2008" "Curl 7.18.0" "Curl Manual"
.SH NAME
curl \- transfer a URL
.SH SYNOPSIS
@ -256,7 +256,7 @@ If this option is used several times, the ones following the first will append
data. As described in \fI-d/--data\fP.
.IP "--data-urlencode <data>"
(HTTP) This posts data, similar to the other --data options with the exception
that this performs URL encoding. (Added in 7.17.2)
that this performs URL encoding. (Added in 7.18.0)
To be CGI compliant, the <data> part should begin with a \fIname\fP followed
by a separator and a content specification. The <data> part can be passed to
@ -1077,7 +1077,7 @@ mutually exclusive.
If this option is used several times, the last one will be used.
.IP "--socks4a <host[:port]>"
Use the specified SOCKS4a proxy. If the port number is not specified, it is
assumed at port 1080. (Added in 7.17.2)
assumed at port 1080. (Added in 7.18.0)
This option overrides any previous use of \fI-x/--proxy\fP, as they are
mutually exclusive.
@ -1086,7 +1086,7 @@ If this option is used several times, the last one will be used.
.IP "--socks5-hostname <host[:port]>"
Use the specified SOCKS5 proxy (and let the proxy resolve the host name). If
the port number is not specified, it is assumed at port 1080. (Added in
7.17.2)
7.18.0)
This option overrides any previous use of \fI-x/--proxy\fP, as they are
mutually exclusive.

7
docs/libcurl/Makefile.am
View file

@ -18,7 +18,8 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \
curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 \
libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3 \
curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3 \
curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3
curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3 \
curl_easy_pause.3
HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \
curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \
@ -36,7 +37,7 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \
curl_share_strerror.html curl_global_init_mem.html libcurl-tutorial.html \
curl_easy_reset.html curl_easy_escape.html curl_easy_unescape.html \
curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html \
curl_formget.html curl_multi_assign.html
curl_formget.html curl_multi_assign.html curl_easy_pause.html
PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \
curl_easy_perform.pdf curl_easy_setopt.pdf curl_easy_duphandle.pdf \
@ -53,7 +54,7 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \
curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf \
curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf \
curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf \
curl_formget.pdf curl_multi_assign.pdf
curl_formget.pdf curl_multi_assign.pdf curl_easy_pause.pdf
CLEANFILES = $(HTMLPAGES) $(PDFPAGES)

63
docs/libcurl/curl_easy_pause.3 Normal file
View file

@ -0,0 +1,63 @@
.\" $Id$
.\"
.TH curl_easy_pause 3 "17 Dec 2007" "libcurl 7.18.0" "libcurl Manual"
.SH NAME
curl_easy_pause - pause and unpause a connection
.SH SYNOPSIS
.B #include <curl/curl.h>
.BI "CURLcode curl_easy_pause(CURL *"handle ", int "bitmask " );"
.SH DESCRIPTION
Using this function, you can explicitly mark a running connection to get
paused, and you can unpause a connection that was previously paused.
A connection can made to pause by using this function or by letting the read
or the write callbacks return the proper magic return code
(\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP).
NOTE: while it may feel tempting, take care and notice that you cannot call
this function from another thread.
When this function is called to unpause reading, the chance is high that you
will get your write callback called before this function returns.
The \fBhandle\fP argument is of course identifying the handle that operates on
the connection you want to pause or unpause.
The \fBbitmask\fP argument is a set of bits that sets the new state of the
connection. The following bits can be used:
.IP CURLPAUSE_RECV
Pause receiving data. There will be no data received on this conneciton until
this function is called again without this bit set. Thus, the write callback
(\fICURLOPT_WRITEFUNCTION\fP) won't be called.
.IP CURLPAUSE_SEND
Pause sending data. There will be no data sent on this connection until this
function is called again without this bit set. Thus, the read callback
(\fICURLOPT_READFUNCTION\fP) won't be called.
.IP CURLPAUSE_ALL
Convenience define that pauses both directions.
.IP CURLPAUSE_CONT
Convenience define that unpauses both directions
.SH RETURN VALUE
CURLE_OK (zero) means that the option was set properly, and a non-zero return
code means something wrong occurred after the new state was set. See the
\fIlibcurl-errors(3)\fP man page for the full list with descriptions.
.SH AVAILABILITY
This function was added in libcurl 7.18.0. Before this version, there was no
explicit support for pausing transfers.
.SH "MEMORY USE"
When pausing a read by returning the magic return code from a write callback,
the read data is already in libcurl's internal buffers so it'll have to keep
it in an allocated buffer until the reading is again unpaused using this
function.
If the downloaded data is compressed and is asked to get uncompressed
automatially on download, libcurl will continue to uncompress the entire
downloaded chunk and it will cache the data uncompressed. This has the side-
effect that if you download something that is compressed a lot, it can result
in a very large data amount needing to be allocated to save the data during
the pause. This said, you should probably consider not using paused reading if
you allow libcurl to uncompress data automatically.
.SH "SEE ALSO"
.BR curl_easy_cleanup "(3), " curl_easy_reset "(3)"

20
docs/libcurl/curl_easy_setopt.3
View file

@ -21,7 +21,7 @@
.\" * $Id$
.\" **************************************************************************
.\"
.TH curl_easy_setopt 3 "5 Jan 2008" "libcurl 7.17.2" "libcurl Manual"
.TH curl_easy_setopt 3 "5 Jan 2008" "libcurl 7.18.0" "libcurl Manual"
.SH NAME
curl_easy_setopt \- set options for a curl easy handle
.SH SYNOPSIS
@ -95,6 +95,10 @@ of bytes actually taken care of. If that amount differs from the amount passed
to your function, it'll signal an error to the library and it will abort the
transfer and return \fICURLE_WRITE_ERROR\fP.
From 7.18.0, the function can return CURL_WRITEFUNC_PAUSE which then will
cause writing to this connection to become paused. See
\fIcurl_easy_pause(3)\fP for further details.
This function may be called with zero bytes data if the transfered file is
empty.
@ -142,6 +146,10 @@ The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
code from the transfer (Added in 7.12.1)
From 7.18.0, the function can return CURL_READFUNC_PAUSE which then will cause
reading from this connection to become paused. See \fIcurl_easy_pause(3)\fP
for further details.
If you set the callback pointer to NULL, or doesn't set it at all, the default
internal read function will be used. It is simply doing an fread() on the FILE
* stream set with \fICURLOPT_READDATA\fP.
@ -431,8 +439,8 @@ specified in the proxy string \fICURLOPT_PROXY\fP.
.IP CURLOPT_PROXYTYPE
Pass a long with this option to set type of the proxy. Available options for
this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2),
\fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP (added in 7.17.2) and
\fICURLPROXY_SOCKS5_HOSTNAME\fP (added in 7.17.2). The HTTP type is
\fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP (added in 7.18.0) and
\fICURLPROXY_SOCKS5_HOSTNAME\fP (added in 7.18.0). The HTTP type is
default. (Added in 7.10)
.IP CURLOPT_HTTPPROXYTUNNEL
Set the parameter to non-zero to get the library to tunnel all operations
@ -443,8 +451,8 @@ don't want this tunneling option.
Set the parameter to 1 to get the library to resolve the host name locally
instead of passing it to the proxy to resolve, when using a SOCKS5 proxy.
Note that libcurl before 7.17.2 always resolved the host name locally even
when SOCKS5 was used. (Added in 7.17.2)
Note that libcurl before 7.18.0 always resolved the host name locally even
when SOCKS5 was used. (Added in 7.18.0)
.IP CURLOPT_INTERFACE
Pass a char * as parameter. This set the interface name to use as outgoing
network interface. The name can be an interface name, an IP address or a host
@ -1080,7 +1088,7 @@ transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by
appending ;type=a or ;type=i to the URL. Without this setting, or it being
set to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when
doing FTP via a proxy. Beware that not all proxies support this feature.
(Added in 7.17.2)
(Added in 7.18.0)
.IP CURLOPT_CRLF
Convert Unix newlines to CRLF newlines on transfers.
.IP CURLOPT_RANGE