Trait curl::easy::Handler

source · [−]
pub trait Handler {
    fn write(&mut self, data: &[u8]) -> Result<usize, WriteError> { ... }
    fn read(&mut self, data: &mut [u8]) -> Result<usize, ReadError> { ... }
    fn seek(&mut self, whence: SeekFrom) -> SeekResult { ... }
    fn debug(&mut self, kind: InfoType, data: &[u8]) { ... }
    fn header(&mut self, data: &[u8]) -> bool { ... }
    fn progress(
        &mut self, 
        dltotal: f64, 
        dlnow: f64, 
        ultotal: f64, 
        ulnow: f64
    ) -> bool { ... }
    fn ssl_ctx(&mut self, cx: *mut c_void) -> Result<(), Error> { ... }
    fn open_socket(
        &mut self, 
        family: c_int, 
        socktype: c_int, 
        protocol: c_int
    ) -> Option<curl_socket_t> { ... }
}
Expand description

A trait for the various callbacks used by libcurl to invoke user code.

This trait represents all operations that libcurl can possibly invoke a client for code during an HTTP transaction. Each callback has a default “noop” implementation, the same as in libcurl. Types implementing this trait may simply override the relevant functions to learn about the callbacks they’re interested in.

Examples

use curl::easy::{Easy2, Handler, WriteError};

struct Collector(Vec<u8>);

impl Handler for Collector {
    fn write(&mut self, data: &[u8]) -> Result<usize, WriteError> {
        self.0.extend_from_slice(data);
        Ok(data.len())
    }
}

let mut easy = Easy2::new(Collector(Vec::new()));
easy.get(true).unwrap();
easy.url("https://www.rust-lang.org/").unwrap();
easy.perform().unwrap();

assert_eq!(easy.response_code().unwrap(), 200);
let contents = easy.get_ref();
println!("{}", String::from_utf8_lossy(&contents.0));

Provided methods

Callback invoked whenever curl has downloaded data for the application.

This callback function gets called by libcurl as soon as there is data received that needs to be saved.

The callback function will be passed as much data as possible in all invokes, but you must not make any assumptions. It may be one byte, it may be thousands. If show_header is enabled, which makes header data get passed to the write callback, you can get up to CURL_MAX_HTTP_HEADER bytes of header data passed into it. This usually means 100K.

This function may be called with zero bytes data if the transferred file is empty.

The callback should return the number of bytes actually taken care of. If that amount differs from the amount passed to your callback function, it’ll signal an error condition to the library. This will cause the transfer to get aborted and the libcurl function used will return an error with is_write_error.

If your callback function returns Err(WriteError::Pause) it will cause this transfer to become paused. See unpause_write for further details.

By default data is sent into the void, and this corresponds to the CURLOPT_WRITEFUNCTION and CURLOPT_WRITEDATA options.

Read callback for data uploads.

This callback function gets called by libcurl as soon as it needs to read data in order to send it to the peer - like if you ask it to upload or post data to the server.

Your function must then return the actual number of bytes that it stored in that memory area. Returning 0 will signal end-of-file to the library and cause it to stop the current transfer.

If you stop the current transfer by returning 0 “pre-maturely” (i.e before the server expected it, like when you’ve said you will upload N bytes and you upload less than N bytes), you may experience that the server “hangs” waiting for the rest of the data that won’t come.

The read callback may return Err(ReadError::Abort) to stop the current operation immediately, resulting in a is_aborted_by_callback error code from the transfer.

The callback can return Err(ReadError::Pause) to cause reading from this connection to pause. See unpause_read for further details.

By default data not input, and this corresponds to the CURLOPT_READFUNCTION and CURLOPT_READDATA options.

Note that the lifetime bound on this function is 'static, but that is often too restrictive. To use stack data consider calling the transfer method and then using read_function to configure a callback that can reference stack-local data.

User callback for seeking in input stream.

This function gets called by libcurl to seek to a certain position in the input stream and can be used to fast forward a file in a resumed upload (instead of reading all uploaded bytes with the normal read function/callback). It is also called to rewind a stream when data has already been sent to the server and needs to be sent again. This may happen when doing a HTTP PUT or POST with a multi-pass authentication method, or when an existing HTTP connection is reused too late and the server closes the connection.

The callback function must return SeekResult::Ok on success, SeekResult::Fail to cause the upload operation to fail or SeekResult::CantSeek to indicate that while the seek failed, libcurl is free to work around the problem if possible. The latter can sometimes be done by instead reading from the input or similar.

By default data this option is not set, and this corresponds to the CURLOPT_SEEKFUNCTION and CURLOPT_SEEKDATA options.

Specify a debug callback

debug_function replaces the standard debug function used when verbose is in effect. This callback receives debug information, as specified in the type argument.

By default this option is not set and corresponds to the CURLOPT_DEBUGFUNCTION and CURLOPT_DEBUGDATA options.

Callback that receives header data

This function gets called by libcurl as soon as it has received header data. The header callback will be called once for each header and only complete header lines are passed on to the callback. Parsing headers is very easy using this. If this callback returns false it’ll signal an error to the library. This will cause the transfer to get aborted and the libcurl function in progress will return is_write_error.

A complete HTTP header that is passed to this function can be up to CURL_MAX_HTTP_HEADER (100K) bytes.

It’s important to note that the callback will be invoked for the headers of all responses received after initiating a request and not just the final response. This includes all responses which occur during authentication negotiation. If you need to operate on only the headers from the final response, you will need to collect headers in the callback yourself and use HTTP status lines, for example, to delimit response boundaries.

When a server sends a chunked encoded transfer, it may contain a trailer. That trailer is identical to a HTTP header and if such a trailer is received it is passed to the application using this callback as well. There are several ways to detect it being a trailer and not an ordinary header: 1) it comes after the response-body. 2) it comes after the final header line (CR LF) 3) a Trailer: header among the regular response-headers mention what header(s) to expect in the trailer.

For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function will get called with the server responses to the commands that libcurl sends.

By default this option is not set and corresponds to the CURLOPT_HEADERFUNCTION and CURLOPT_HEADERDATA options.

Callback to progress meter function

This function gets called by libcurl instead of its internal equivalent with a frequent interval. While data is being transferred it will be called very frequently, and during slow periods like when nothing is being transferred it can slow down to about one call per second.

The callback gets told how much data libcurl will transfer and has transferred, in number of bytes. The first argument is the total number of bytes libcurl expects to download in this transfer. The second argument is the number of bytes downloaded so far. The third argument is the total number of bytes libcurl expects to upload in this transfer. The fourth argument is the number of bytes uploaded so far.

Unknown/unused argument values passed to the callback will be set to zero (like if you only download data, the upload size will remain 0). Many times the callback will be called one or more times first, before it knows the data sizes so a program must be made to handle that.

Returning false from this callback will cause libcurl to abort the transfer and return is_aborted_by_callback.

If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl function that performs transfers.

progress must be set to true to make this function actually get called.

By default this function calls an internal method and corresponds to CURLOPT_PROGRESSFUNCTION and CURLOPT_PROGRESSDATA.

Callback to SSL context

This callback function gets called by libcurl just before the initialization of an SSL connection after having processed all other SSL related options to give a last chance to an application to modify the behaviour of the SSL initialization. The ssl_ctx parameter is actually a pointer to the SSL library’s SSL_CTX. If an error is returned from the callback no attempt to establish a connection is made and the perform operation will return the callback’s error code.

This function will get called on all new connections made to a server, during the SSL negotiation. The SSL_CTX pointer will be a new one every time.

To use this properly, a non-trivial amount of knowledge of your SSL library is necessary. For example, you can use this function to call library-specific callbacks to add additional validation code for certificates, and even to change the actual URI of a HTTPS request.

By default this function calls an internal method and corresponds to CURLOPT_SSL_CTX_FUNCTION and CURLOPT_SSL_CTX_DATA.

Note that this callback is not guaranteed to be called, not all versions of libcurl support calling this callback.

Callback to open sockets for libcurl.

This callback function gets called by libcurl instead of the socket(2) call. The callback function should return the newly created socket or None in case no connection could be established or another error was detected. Any additional setsockopt(2) calls can of course be done on the socket at the user’s discretion. A None return value from the callback function will signal an unrecoverable error to libcurl and it will return is_couldnt_connect from the function that triggered this callback.

By default this function opens a standard socket and corresponds to CURLOPT_OPENSOCKETFUNCTION .

Implementors