curl_easy_pause

Syntax

#include <curl/curl.h>

CURLcode curl_easy_pause(CURL *handle , int bitmask );

Parameters

handle Handle to a curl session.
bitmask Bits that set the new state of the connection.

Return Values

If the operation was successful, CURLE_OK is returned. Otherwise, a specific libcurl Error Code is returned. A nonzero return code indicates an issue occurred after the new state was set.

Description

Use this function to explicitly mark a running connection to pause or, alternatively, unpause a connection that was previously paused.

A connection can be paused by using this function or by letting the read or the write callbacks return the proper magic return code (CURL_READFUNC_PAUSE and CURL_WRITEFUNC_PAUSE). A write callback returns pause signals to the library stating that it could not take care of any data, and that the data will then be delivered again to the callback when the writing is later unpaused.

NOTE:
Do not call this function from another thread.

When this function is called to unpause reading, it is likely that the write callback is called before this function returns. The handle argument is identifying the handle that operates on the connection required to pause or unpause. The bitmask argument is a set of bits that sets the new state of the connection. The following bits can be used.

CURLPAUSE_RECV

Pause receiving data. There will be no data received on this connection until this function is called again without this bit set. The write callback CURLOPT_WRITEFUNCTION will not be called.

CURLPAUSE_SEND

Pause sending data. There will be no data sent on this connection until this function is called again without this bit set. The read callback CURLOPT_READFUNCTION will not be called.

CURLPAUSE_ALL

Convenience define that pauses both directions.

CURLPAUSE_CONT

Convenience define that unpauses both directions.

Availability

This function was added in libcurl 7.18.0. Before this version, there was no explicit support for pausing transfers.

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 will 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 automatically 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 downloading something that is highly compressed, it can result in a large data amount allocation in to save the data during the pause. Consider not using paused reading if allowing libcurl to uncompress data automatically.

Do Not Call From

None.

See Also

HTTP Client Library (libcurl)
libcurl API Functions
libcurl Error Codes
curl_easy_cleanup
curl_easy_reset

Revision History

2013/09/18 Conversion
2013/05/08 Automated cleanup pass.
2012/05/04 Initial version.


CONFIDENTIAL