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

and the write callbacks that now can make a connection's reading and/or
writing get paused.

3 files changed, 81 insertions, 9 deletions

diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am
index dbc04ce57..9bf8e99c7 100644
--- a/docs/libcurl/Makefile.am
+++ b/docs/libcurl/Makefile.am
@@ -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)
 
diff --git a/docs/libcurl/curl_easy_pause.3 b/docs/libcurl/curl_easy_pause.3
new file mode 100644
index 000000000..247b39c27
--- /dev/null
+++ b/docs/libcurl/curl_easy_pause.3
@@ -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)"
diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index 05289e9de..96f2d2b2c 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -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