[−][src]Trait curl::easy::Handler
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
fn write(&mut self, data: &[u8]) -> Result<usize, WriteError>
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.
fn read(&mut self, data: &mut [u8]) -> Result<usize, ReadError>
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.
fn seek(&mut self, whence: SeekFrom) -> SeekResult
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.
fn debug(&mut self, kind: InfoType, data: &[u8])
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.
fn header(&mut self, data: &[u8]) -> bool
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.
fn progress(
&mut self,
dltotal: f64,
dlnow: f64,
ultotal: f64,
ulnow: f64
) -> bool
&mut self,
dltotal: f64,
dlnow: f64,
ultotal: f64,
ulnow: f64
) -> bool
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.
fn ssl_ctx(&mut self, cx: *mut c_void) -> Result<(), Error>
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.
fn open_socket(
&mut self,
family: c_int,
socktype: c_int,
protocol: c_int
) -> Option<curl_socket_t>
&mut self,
family: c_int,
socktype: c_int,
protocol: c_int
) -> Option<curl_socket_t>
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 .