Struct curl::easy::Easy2

pub struct Easy2<H> { /* fields omitted */ }

Raw bindings to a libcurl "easy session".

This type corresponds to the CURL type in libcurl, and is probably what you want for just sending off a simple HTTP request and fetching a response. Each easy handle can be thought of as a large builder before calling the final perform function.

There are many many configuration options for each Easy2 handle, and they should all have their own documentation indicating what it affects and how it interacts with other options. Some implementations of libcurl can use this handle to interact with many different protocols, although by default this crate only guarantees the HTTP/HTTPS protocols working.

Note that almost all methods on this structure which configure various properties return a Result. This is largely used to detect whether the underlying implementation of libcurl actually implements the option being requested. If you're linked to a version of libcurl which doesn't support the option, then an error will be returned. Some options also perform some validation when they're set, and the error is returned through this vector.

Note that historically this library contained an Easy handle so this one's called Easy2. The major difference between the Easy type is that an Easy2 structure uses a trait instead of closures for all of the callbacks that curl can invoke. The Easy type is actually built on top of this Easy type, and this Easy2 type can be more flexible in some situations due to the generic parameter.

There's not necessarily a right answer for which type is correct to use, but as a general rule of thumb Easy is typically a reasonable choice for synchronous I/O and Easy2 is a good choice for asynchronous I/O.

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));

Methods

impl<H: Handler> Easy2<H>

pub fn new(handler: H) -> Easy2<H>

Creates a new "easy" handle which is the core of almost all operations in libcurl.

To use a handle, applications typically configure a number of options followed by a call to perform. Options are preserved across calls to perform and need to be reset manually (or via the reset method) if this is not desired.

pub fn reset(&mut self)

Re-initializes this handle to the default values.

This puts the handle to the same state as it was in when it was just created. This does, however, keep live connections, the session id cache, the dns cache, and cookies.

impl<H> Easy2<H>

pub fn verbose(&mut self, verbose: bool) -> Result<(), Error>

Configures this handle to have verbose output to help debug protocol information.

By default output goes to stderr, but the stderr function on this type can configure that. You can also use the debug_function method to get all protocol data sent and received.

By default, this option is false.

pub fn show_header(&mut self, show: bool) -> Result<(), Error>

Indicates whether header information is streamed to the output body of this request.

This option is only relevant for protocols which have header metadata (like http or ftp). It's not generally possible to extract headers from the body if using this method, that use case should be intended for the header_function method.

To set HTTP headers, use the http_header method.

By default, this option is false and corresponds to CURLOPT_HEADER.

pub fn progress(&mut self, progress: bool) -> Result<(), Error>

Indicates whether a progress meter will be shown for requests done with this handle.

This will also prevent the progress_function from being called.

By default this option is false and corresponds to CURLOPT_NOPROGRESS.

pub fn signal(&mut self, signal: bool) -> Result<(), Error>

Inform libcurl whether or not it should install signal handlers or attempt to use signals to perform library functions.

If this option is disabled then timeouts during name resolution will not work unless libcurl is built against c-ares. Note that enabling this option, however, may not cause libcurl to work with multiple threads.

By default this option is false and corresponds to CURLOPT_NOSIGNAL. Note that this default is different than libcurl as it is intended that this library is threadsafe by default. See the libcurl docs for some more information.

pub fn wildcard_match(&mut self, m: bool) -> Result<(), Error>

Indicates whether multiple files will be transferred based on the file name pattern.

The last part of a filename uses fnmatch-like pattern matching.

By default this option is false and corresponds to CURLOPT_WILDCARDMATCH.

pub fn unix_socket(&mut self, unix_domain_socket: &str) -> Result<(), Error>

Provides the unix domain socket which this handle will work with.

The string provided must be unix domain socket -encoded with the format:

/path/file.sock

pub fn get_ref(&self) -> &H

Acquires a reference to the underlying handler for events.

pub fn get_mut(&mut self) -> &mut H

Acquires a reference to the underlying handler for events.

pub fn fail_on_error(&mut self, fail: bool) -> Result<(), Error>

Indicates whether this library will fail on HTTP response codes >= 400.

This method is not fail-safe especially when authentication is involved.

By default this option is false and corresponds to CURLOPT_FAILONERROR.

pub fn url(&mut self, url: &str) -> Result<(), Error>

Provides the URL which this handle will work with.

The string provided must be URL-encoded with the format:

scheme://host:port/path

The syntax is not validated as part of this function and that is deferred until later.

By default this option is not set and perform will not work until it is set. This option corresponds to CURLOPT_URL.

pub fn port(&mut self, port: u16) -> Result<(), Error>

Configures the port number to connect to, instead of the one specified in the URL or the default of the protocol.

pub fn proxy(&mut self, url: &str) -> Result<(), Error>

Provide the URL of a proxy to use.

By default this option is not set and corresponds to CURLOPT_PROXY.

pub fn proxy_port(&mut self, port: u16) -> Result<(), Error>

Provide port number the proxy is listening on.

By default this option is not set (the default port for the proxy protocol is used) and corresponds to CURLOPT_PROXYPORT.

pub fn proxy_type(&mut self, kind: ProxyType) -> Result<(), Error>

Indicates the type of proxy being used.

By default this option is ProxyType::Http and corresponds to CURLOPT_PROXYTYPE.

pub fn noproxy(&mut self, skip: &str) -> Result<(), Error>

Provide a list of hosts that should not be proxied to.

This string is a comma-separated list of hosts which should not use the proxy specified for connections. A single * character is also accepted as a wildcard for all hosts.

By default this option is not set and corresponds to CURLOPT_NOPROXY.

pub fn http_proxy_tunnel(&mut self, tunnel: bool) -> Result<(), Error>

Inform curl whether it should tunnel all operations through the proxy.

This essentially means that a CONNECT is sent to the proxy for all outbound requests.

By default this option is false and corresponds to CURLOPT_HTTPPROXYTUNNEL.

pub fn interface(&mut self, interface: &str) -> Result<(), Error>

Tell curl which interface to bind to for an outgoing network interface.

The interface name, IP address, or host name can be specified here.

By default this option is not set and corresponds to CURLOPT_INTERFACE.

pub fn set_local_port(&mut self, port: u16) -> Result<(), Error>

Indicate which port should be bound to locally for this connection.

By default this option is 0 (any port) and corresponds to CURLOPT_LOCALPORT.

pub fn local_port_range(&mut self, range: u16) -> Result<(), Error>

Indicates the number of attempts libcurl will perform to find a working port number.

By default this option is 1 and corresponds to CURLOPT_LOCALPORTRANGE.

pub fn dns_servers(&mut self, servers: &str) -> Result<(), Error>

Sets the DNS servers that wil be used.

Provide a comma separated list, for example: 8.8.8.8,8.8.4.4.

By default this option is not set and the OS's DNS resolver is used. This option can only be used if libcurl is linked against c-ares, otherwise setting it will return an error.

pub fn dns_cache_timeout(&mut self, dur: Duration) -> Result<(), Error>

Sets the timeout of how long name resolves will be kept in memory.

This is distinct from DNS TTL options and is entirely speculative.

By default this option is 60s and corresponds to CURLOPT_DNS_CACHE_TIMEOUT.

pub fn buffer_size(&mut self, size: usize) -> Result<(), Error>

Specify the preferred receive buffer size, in bytes.

This is treated as a request, not an order, and the main point of this is that the write callback may get called more often with smaller chunks.

By default this option is the maximum write size and corresopnds to CURLOPT_BUFFERSIZE.

pub fn tcp_nodelay(&mut self, enable: bool) -> Result<(), Error>

Configures whether the TCP_NODELAY option is set, or Nagle's algorithm is disabled.

The purpose of Nagle's algorithm is to minimize the number of small packet's on the network, and disabling this may be less efficient in some situations.

By default this option is false and corresponds to CURLOPT_TCP_NODELAY.

pub fn tcp_keepalive(&mut self, enable: bool) -> Result<(), Error>

Configures whether TCP keepalive probes will be sent.

The delay and frequency of these probes is controlled by tcp_keepidle and tcp_keepintvl.

By default this option is false and corresponds to CURLOPT_TCP_KEEPALIVE.

pub fn tcp_keepidle(&mut self, amt: Duration) -> Result<(), Error>

Configures the TCP keepalive idle time wait.

This is the delay, after which the connection is idle, keepalive probes will be sent. Not all operating systems support this.

By default this corresponds to CURLOPT_TCP_KEEPIDLE.

pub fn tcp_keepintvl(&mut self, amt: Duration) -> Result<(), Error>

Configures the delay between keepalive probes.

By default this corresponds to CURLOPT_TCP_KEEPINTVL.

pub fn address_scope(&mut self, scope: u32) -> Result<(), Error>

Configures the scope for local IPv6 addresses.

Sets the scope_id value to use when connecting to IPv6 or link-local addresses.

By default this value is 0 and corresponds to CURLOPT_ADDRESS_SCOPE

pub fn username(&mut self, user: &str) -> Result<(), Error>

Configures the username to pass as authentication for this connection.

By default this value is not set and corresponds to CURLOPT_USERNAME.

pub fn password(&mut self, pass: &str) -> Result<(), Error>

Configures the password to pass as authentication for this connection.

By default this value is not set and corresponds to CURLOPT_PASSWORD.

pub fn http_auth(&mut self, auth: &Auth) -> Result<(), Error>

Set HTTP server authentication methods to try

If more than one method is set, libcurl will first query the site to see which authentication methods it supports and then pick the best one you allow it to use. For some methods, this will induce an extra network round-trip. Set the actual name and password with the password and username methods.

For authentication with a proxy, see proxy_auth.

By default this value is basic and corresponds to CURLOPT_HTTPAUTH.

pub fn proxy_username(&mut self, user: &str) -> Result<(), Error>

Configures the proxy username to pass as authentication for this connection.

By default this value is not set and corresponds to CURLOPT_PROXYUSERNAME.

pub fn proxy_password(&mut self, pass: &str) -> Result<(), Error>

Configures the proxy password to pass as authentication for this connection.

By default this value is not set and corresponds to CURLOPT_PROXYPASSWORD.

pub fn proxy_auth(&mut self, auth: &Auth) -> Result<(), Error>

Set HTTP proxy authentication methods to try

If more than one method is set, libcurl will first query the site to see which authentication methods it supports and then pick the best one you allow it to use. For some methods, this will induce an extra network round-trip. Set the actual name and password with the proxy_password and proxy_username methods.

By default this value is basic and corresponds to CURLOPT_PROXYAUTH.

pub fn netrc(&mut self, netrc: NetRc) -> Result<(), Error>

Enable .netrc parsing

By default the .netrc file is ignored and corresponds to CURL_NETRC_IGNORED.

pub fn autoreferer(&mut self, enable: bool) -> Result<(), Error>

Indicates whether the referer header is automatically updated

By default this option is false and corresponds to CURLOPT_AUTOREFERER.

pub fn accept_encoding(&mut self, encoding: &str) -> Result<(), Error>

Enables automatic decompression of HTTP downloads.

Sets the contents of the Accept-Encoding header sent in an HTTP request. This enables decoding of a response with Content-Encoding.

Currently supported encoding are identity, zlib, and gzip. A zero-length string passed in will send all accepted encodings.

By default this option is not set and corresponds to CURLOPT_ACCEPT_ENCODING.

pub fn transfer_encoding(&mut self, enable: bool) -> Result<(), Error>

Request the HTTP Transfer Encoding.

By default this option is false and corresponds to CURLOPT_TRANSFER_ENCODING.

pub fn follow_location(&mut self, enable: bool) -> Result<(), Error>

Follow HTTP 3xx redirects.

Indicates whether any Location headers in the response should get followed.

By default this option is false and corresponds to CURLOPT_FOLLOWLOCATION.

pub fn unrestricted_auth(&mut self, enable: bool) -> Result<(), Error>

Send credentials to hosts other than the first as well.

Sends username/password credentials even when the host changes as part of a redirect.

By default this option is false and corresponds to CURLOPT_UNRESTRICTED_AUTH.

pub fn max_redirections(&mut self, max: u32) -> Result<(), Error>

Set the maximum number of redirects allowed.

A value of 0 will refuse any redirect.

By default this option is -1 (unlimited) and corresponds to CURLOPT_MAXREDIRS.

pub fn put(&mut self, enable: bool) -> Result<(), Error>

Make an HTTP PUT request.

By default this option is false and corresponds to CURLOPT_PUT.

pub fn post(&mut self, enable: bool) -> Result<(), Error>

Make an HTTP POST request.

This will also make the library use the Content-Type: application/x-www-form-urlencoded header.

POST data can be specified through post_fields or by specifying a read function.

By default this option is false and corresponds to CURLOPT_POST.

pub fn post_fields_copy(&mut self, data: &[u8]) -> Result<(), Error>

Configures the data that will be uploaded as part of a POST.

Note that the data is copied into this handle and if that's not desired then the read callbacks can be used instead.

By default this option is not set and corresponds to CURLOPT_COPYPOSTFIELDS.

pub fn post_field_size(&mut self, size: u64) -> Result<(), Error>

Configures the size of data that's going to be uploaded as part of a POST operation.

This is called automatically as part of post_fields and should only be called if data is being provided in a read callback (and even then it's optional).

By default this option is not set and corresponds to CURLOPT_POSTFIELDSIZE_LARGE.

pub fn httppost(&mut self, form: Form) -> Result<(), Error>

Tells libcurl you want a multipart/formdata HTTP POST to be made and you instruct what data to pass on to the server in the form argument.

By default this option is set to null and corresponds to CURLOPT_HTTPPOST.

pub fn referer(&mut self, referer: &str) -> Result<(), Error>

Sets the HTTP referer header

By default this option is not set and corresponds to CURLOPT_REFERER.

pub fn useragent(&mut self, useragent: &str) -> Result<(), Error>

Sets the HTTP user-agent header

By default this option is not set and corresponds to CURLOPT_USERAGENT.

pub fn http_headers(&mut self, list: List) -> Result<(), Error>

Add some headers to this HTTP request.

If you add a header that is otherwise used internally, the value here takes precedence. If a header is added with no content (like Accept:) the internally the header will get disabled. To add a header with no content, use the form MyHeader; (not the trailing semicolon).

Headers must not be CRLF terminated. Many replaced headers have common shortcuts which should be prefered.

By default this option is not set and corresponds to CURLOPT_HTTPHEADER

Examples

use curl::easy::{Easy, List};

let mut list = List::new();
list.append("Foo: bar").unwrap();
list.append("Bar: baz").unwrap();

let mut handle = Easy::new();
handle.url("https://www.rust-lang.org/").unwrap();
handle.http_headers(list).unwrap();
handle.perform().unwrap();

pub fn cookie(&mut self, cookie: &str) -> Result<(), Error>

Set the contents of the HTTP Cookie header.

Pass a string of the form name=contents for one cookie value or name1=val1; name2=val2 for multiple values.

Using this option multiple times will only make the latest string override the previous ones. This option will not enable the cookie engine, use cookie_file or cookie_jar to do that.

By default this option is not set and corresponds to CURLOPT_COOKIE.

pub fn cookie_file<P: AsRef<Path>>(&mut self, file: P) -> Result<(), Error>

Set the file name to read cookies from.

The cookie data can be in either the old Netscape / Mozilla cookie data format or just regular HTTP headers (Set-Cookie style) dumped to a file.

This also enables the cookie engine, making libcurl parse and send cookies on subsequent requests with this handle.

Given an empty or non-existing file or by passing the empty string ("") to this option, you can enable the cookie engine without reading any initial cookies.

If you use this option multiple times, you just add more files to read. Subsequent files will add more cookies.

By default this option is not set and corresponds to CURLOPT_COOKIEFILE.

pub fn cookie_jar<P: AsRef<Path>>(&mut self, file: P) -> Result<(), Error>

Set the file name to store cookies to.

This will make libcurl write all internally known cookies to the file when this handle is dropped. If no cookies are known, no file will be created. Specify "-" as filename to instead have the cookies written to stdout. Using this option also enables cookies for this session, so if you for example follow a location it will make matching cookies get sent accordingly.

Note that libcurl doesn't read any cookies from the cookie jar. If you want to read cookies from a file, use cookie_file.

By default this option is not set and corresponds to CURLOPT_COOKIEJAR.

pub fn cookie_session(&mut self, session: bool) -> Result<(), Error>

Start a new cookie session

Marks this as a new cookie "session". It will force libcurl to ignore all cookies it is about to load that are "session cookies" from the previous session. By default, libcurl always stores and loads all cookies, independent if they are session cookies or not. Session cookies are cookies without expiry date and they are meant to be alive and existing for this "session" only.

By default this option is false and corresponds to CURLOPT_COOKIESESSION.

pub fn cookie_list(&mut self, cookie: &str) -> Result<(), Error>

Add to or manipulate cookies held in memory.

Such a cookie can be either a single line in Netscape / Mozilla format or just regular HTTP-style header (Set-Cookie: ...) format. This will also enable the cookie engine. This adds that single cookie to the internal cookie store.

Exercise caution if you are using this option and multiple transfers may occur. If you use the Set-Cookie format and don't specify a domain then the cookie is sent for any domain (even after redirects are followed) and cannot be modified by a server-set cookie. If a server sets a cookie of the same name (or maybe you've imported one) then both will be sent on a future transfer to that server, likely not what you intended. address these issues set a domain in Set-Cookie or use the Netscape format.

Additionally, there are commands available that perform actions if you pass in these exact strings:

• "ALL" - erases all cookies held in memory
• "SESS" - erases all session cookies held in memory
• "FLUSH" - write all known cookies to the specified cookie jar
• "RELOAD" - reread all cookies from the cookie file

By default this options corresponds to CURLOPT_COOKIELIST

pub fn get(&mut self, enable: bool) -> Result<(), Error>

Ask for a HTTP GET request.

By default this option is false and corresponds to CURLOPT_HTTPGET.

pub fn ignore_content_length(&mut self, ignore: bool) -> Result<(), Error>

Ignore the content-length header.

By default this option is false and corresponds to CURLOPT_IGNORE_CONTENT_LENGTH.

pub fn http_content_decoding(&mut self, enable: bool) -> Result<(), Error>

Enable or disable HTTP content decoding.

By default this option is true and corresponds to CURLOPT_HTTP_CONTENT_DECODING.

pub fn http_transfer_decoding(&mut self, enable: bool) -> Result<(), Error>

Enable or disable HTTP transfer decoding.

By default this option is true and corresponds to CURLOPT_HTTP_TRANSFER_DECODING.

pub fn range(&mut self, range: &str) -> Result<(), Error>

Indicates the range that this request should retrieve.

The string provided should be of the form N-M where either N or M can be left out. For HTTP transfers multiple ranges separated by commas are also accepted.

By default this option is not set and corresponds to CURLOPT_RANGE.

pub fn resume_from(&mut self, from: u64) -> Result<(), Error>

Set a point to resume transfer from

Specify the offset in bytes you want the transfer to start from.

By default this option is 0 and corresponds to CURLOPT_RESUME_FROM_LARGE.

pub fn custom_request(&mut self, request: &str) -> Result<(), Error>

Set a custom request string

Specifies that a custom request will be made (e.g. a custom HTTP method). This does not change how libcurl performs internally, just changes the string sent to the server.

By default this option is not set and corresponds to CURLOPT_CUSTOMREQUEST.

pub fn fetch_filetime(&mut self, fetch: bool) -> Result<(), Error>

Get the modification time of the remote resource

If true, libcurl will attempt to get the modification time of the remote document in this operation. This requires that the remote server sends the time or replies to a time querying command. The filetime function can be used after a transfer to extract the received time (if any).

By default this option is false and corresponds to CURLOPT_FILETIME

pub fn nobody(&mut self, enable: bool) -> Result<(), Error>

Indicate whether to download the request without getting the body

This is useful, for example, for doing a HEAD request.

By default this option is false and corresponds to CURLOPT_NOBODY.

pub fn in_filesize(&mut self, size: u64) -> Result<(), Error>

Set the size of the input file to send off.

By default this option is not set and corresponds to CURLOPT_INFILESIZE_LARGE.

pub fn upload(&mut self, enable: bool) -> Result<(), Error>

Enable or disable data upload.

This means that a PUT request will be made for HTTP and probably wants to be combined with the read callback as well as the in_filesize method.

By default this option is false and corresponds to CURLOPT_UPLOAD.

pub fn max_filesize(&mut self, size: u64) -> Result<(), Error>

Configure the maximum file size to download.

By default this option is not set and corresponds to CURLOPT_MAXFILESIZE_LARGE.

pub fn time_condition(&mut self, cond: TimeCondition) -> Result<(), Error>

Selects a condition for a time request.

This value indicates how the time_value option is interpreted.

By default this option is not set and corresponds to CURLOPT_TIMECONDITION.

pub fn time_value(&mut self, val: i64) -> Result<(), Error>

Sets the time value for a conditional request.

The value here should be the number of seconds elapsed since January 1, 1970. To pass how to interpret this value, use time_condition.

By default this option is not set and corresponds to CURLOPT_TIMEVALUE.

pub fn timeout(&mut self, timeout: Duration) -> Result<(), Error>

Set maximum time the request is allowed to take.

Normally, name lookups can take a considerable time and limiting operations to less than a few minutes risk aborting perfectly normal operations.

If libcurl is built to use the standard system name resolver, that portion of the transfer will still use full-second resolution for timeouts with a minimum timeout allowed of one second.

In unix-like systems, this might cause signals to be used unless nosignal is set.

Since this puts a hard limit for how long a request is allowed to take, it has limited use in dynamic use cases with varying transfer times. You are then advised to explore low_speed_limit, low_speed_time or using progress_function to implement your own timeout logic.

By default this option is not set and corresponds to CURLOPT_TIMEOUT_MS.

pub fn low_speed_limit(&mut self, limit: u32) -> Result<(), Error>

Set the low speed limit in bytes per second.

This specifies the average transfer speed in bytes per second that the transfer should be below during low_speed_time for libcurl to consider it to be too slow and abort.

By default this option is not set and corresponds to CURLOPT_LOW_SPEED_LIMIT.

pub fn low_speed_time(&mut self, dur: Duration) -> Result<(), Error>

Set the low speed time period.

Specifies the window of time for which if the transfer rate is below low_speed_limit the request will be aborted.

By default this option is not set and corresponds to CURLOPT_LOW_SPEED_TIME.

pub fn max_send_speed(&mut self, speed: u64) -> Result<(), Error>

Rate limit data upload speed

If an upload exceeds this speed (counted in bytes per second) on cumulative average during the transfer, the transfer will pause to keep the average rate less than or equal to the parameter value.

By default this option is not set (unlimited speed) and corresponds to CURLOPT_MAX_SEND_SPEED_LARGE.

pub fn max_recv_speed(&mut self, speed: u64) -> Result<(), Error>

Rate limit data download speed

If a download exceeds this speed (counted in bytes per second) on cumulative average during the transfer, the transfer will pause to keep the average rate less than or equal to the parameter value.

By default this option is not set (unlimited speed) and corresponds to CURLOPT_MAX_RECV_SPEED_LARGE.

pub fn max_connects(&mut self, max: u32) -> Result<(), Error>

Set the maximum connection cache size.

The set amount will be the maximum number of simultaneously open persistent connections that libcurl may cache in the pool associated with this handle. The default is 5, and there isn't much point in changing this value unless you are perfectly aware of how this works and changes libcurl's behaviour. This concerns connections using any of the protocols that support persistent connections.

When reaching the maximum limit, curl closes the oldest one in the cache to prevent increasing the number of open connections.

By default this option is set to 5 and corresponds to CURLOPT_MAXCONNECTS

pub fn fresh_connect(&mut self, enable: bool) -> Result<(), Error>

Force a new connection to be used.

Makes the next transfer use a new (fresh) connection by force instead of trying to re-use an existing one. This option should be used with caution and only if you understand what it does as it may seriously impact performance.

By default this option is false and corresponds to CURLOPT_FRESH_CONNECT.

pub fn forbid_reuse(&mut self, enable: bool) -> Result<(), Error>

Make connection get closed at once after use.

Makes libcurl explicitly close the connection when done with the transfer. Normally, libcurl keeps all connections alive when done with one transfer in case a succeeding one follows that can re-use them. This option should be used with caution and only if you understand what it does as it can seriously impact performance.

By default this option is false and corresponds to CURLOPT_FORBID_REUSE.

pub fn connect_timeout(&mut self, timeout: Duration) -> Result<(), Error>

Timeout for the connect phase

This is the maximum time that you allow the connection phase to the server to take. This only limits the connection phase, it has no impact once it has connected.

By default this value is 300 seconds and corresponds to CURLOPT_CONNECTTIMEOUT_MS.

pub fn ip_resolve(&mut self, resolve: IpResolve) -> Result<(), Error>

Specify which IP protocol version to use

Allows an application to select what kind of IP addresses to use when resolving host names. This is only interesting when using host names that resolve addresses using more than one version of IP.

By default this value is "any" and corresponds to CURLOPT_IPRESOLVE.

pub fn resolve(&mut self, list: List) -> Result<(), Error>

Specify custom host name to IP address resolves.

Allows specifying hostname to IP mappins to use before trying the system resolver.

Examples

use curl::easy::{Easy, List};

let mut list = List::new();
list.append("www.rust-lang.org:443:185.199.108.153").unwrap();

let mut handle = Easy::new();
handle.url("https://www.rust-lang.org/").unwrap();
handle.resolve(list).unwrap();
handle.perform().unwrap();

pub fn connect_only(&mut self, enable: bool) -> Result<(), Error>

Configure whether to stop when connected to target server

When enabled it tells the library to perform all the required proxy authentication and connection setup, but no data transfer, and then return.

The option can be used to simply test a connection to a server.

By default this value is false and corresponds to CURLOPT_CONNECT_ONLY.

pub fn ssl_cert<P: AsRef<Path>>(&mut self, cert: P) -> Result<(), Error>

Sets the SSL client certificate.

The string should be the file name of your client certificate. The default format is "P12" on Secure Transport and "PEM" on other engines, and can be changed with ssl_cert_type.

With NSS or Secure Transport, this can also be the nickname of the certificate you wish to authenticate with as it is named in the security database. If you want to use a file from the current directory, please precede it with "./" prefix, in order to avoid confusion with a nickname.

When using a client certificate, you most likely also need to provide a private key with ssl_key.

By default this option is not set and corresponds to CURLOPT_SSLCERT.

pub fn ssl_cert_type(&mut self, kind: &str) -> Result<(), Error>

Specify type of the client SSL certificate.

The string should be the format of your certificate. Supported formats are "PEM" and "DER", except with Secure Transport. OpenSSL (versions 0.9.3 and later) and Secure Transport (on iOS 5 or later, or OS X 10.7 or later) also support "P12" for PKCS#12-encoded files.

By default this option is "PEM" and corresponds to CURLOPT_SSLCERTTYPE.

pub fn ssl_key<P: AsRef<Path>>(&mut self, key: P) -> Result<(), Error>

Specify private keyfile for TLS and SSL client cert.

The string should be the file name of your private key. The default format is "PEM" and can be changed with ssl_key_type.

(iOS and Mac OS X only) This option is ignored if curl was built against Secure Transport. Secure Transport expects the private key to be already present in the keychain or PKCS#12 file containing the certificate.

By default this option is not set and corresponds to CURLOPT_SSLKEY.

pub fn ssl_key_type(&mut self, kind: &str) -> Result<(), Error>

Set type of the private key file.

The string should be the format of your private key. Supported formats are "PEM", "DER" and "ENG".

The format "ENG" enables you to load the private key from a crypto engine. In this case ssl_key is used as an identifier passed to the engine. You have to set the crypto engine with ssl_engine. "DER" format key file currently does not work because of a bug in OpenSSL.

By default this option is "PEM" and corresponds to CURLOPT_SSLKEYTYPE.

pub fn key_password(&mut self, password: &str) -> Result<(), Error>

Set passphrase to private key.

This will be used as the password required to use the ssl_key. You never needed a pass phrase to load a certificate but you need one to load your private key.

By default this option is not set and corresponds to CURLOPT_KEYPASSWD.

pub fn ssl_engine(&mut self, engine: &str) -> Result<(), Error>

Set the SSL engine identifier.

This will be used as the identifier for the crypto engine you want to use for your private key.

By default this option is not set and corresponds to CURLOPT_SSLENGINE.

pub fn ssl_engine_default(&mut self, enable: bool) -> Result<(), Error>

Make this handle's SSL engine the default.

By default this option is not set and corresponds to CURLOPT_SSLENGINE_DEFAULT.

pub fn http_version(&mut self, version: HttpVersion) -> Result<(), Error>

Set preferred HTTP version.

By default this option is not set and corresponds to CURLOPT_HTTP_VERSION.

pub fn ssl_version(&mut self, version: SslVersion) -> Result<(), Error>

Set preferred TLS/SSL version.

By default this option is not set and corresponds to CURLOPT_SSLVERSION.

pub fn ssl_min_max_version(
    &mut self,
    min_version: SslVersion,
    max_version: SslVersion
) -> Result<(), Error>

Set preferred TLS/SSL version with minimum version and maximum version.

By default this option is not set and corresponds to CURLOPT_SSLVERSION.

pub fn ssl_verify_host(&mut self, verify: bool) -> Result<(), Error>

Verify the certificate's name against host.

This should be disabled with great caution! It basically disables the security features of SSL if it is disabled.

By default this option is set to true and corresponds to CURLOPT_SSL_VERIFYHOST.

pub fn ssl_verify_peer(&mut self, verify: bool) -> Result<(), Error>

Verify the peer's SSL certificate.

This should be disabled with great caution! It basically disables the security features of SSL if it is disabled.

By default this option is set to true and corresponds to CURLOPT_SSL_VERIFYPEER.

pub fn cainfo<P: AsRef<Path>>(&mut self, path: P) -> Result<(), Error>

Specify the path to Certificate Authority (CA) bundle

The file referenced should hold one or more certificates to verify the peer with.

This option is by default set to the system path where libcurl's cacert bundle is assumed to be stored, as established at build time.

If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module (libnsspem.so) needs to be available for this option to work properly.

By default this option is the system defaults, and corresponds to CURLOPT_CAINFO.

pub fn issuer_cert<P: AsRef<Path>>(&mut self, path: P) -> Result<(), Error>

Set the issuer SSL certificate filename

Specifies a file holding a CA certificate in PEM format. If the option is set, an additional check against the peer certificate is performed to verify the issuer is indeed the one associated with the certificate provided by the option. This additional check is useful in multi-level PKI where one needs to enforce that the peer certificate is from a specific branch of the tree.

This option makes sense only when used in combination with the ssl_verify_peer option. Otherwise, the result of the check is not considered as failure.

By default this option is not set and corresponds to CURLOPT_ISSUERCERT.

pub fn capath<P: AsRef<Path>>(&mut self, path: P) -> Result<(), Error>

Specify directory holding CA certificates

Names a directory holding multiple CA certificates to verify the peer with. If libcurl is built against OpenSSL, the certificate directory must be prepared using the openssl c_rehash utility. This makes sense only when used in combination with the ssl_verify_peer option.

By default this option is not set and corresponds to CURLOPT_CAPATH.

pub fn crlfile<P: AsRef<Path>>(&mut self, path: P) -> Result<(), Error>

Specify a Certificate Revocation List file

Names a file with the concatenation of CRL (in PEM format) to use in the certificate validation that occurs during the SSL exchange.

When curl is built to use NSS or GnuTLS, there is no way to influence the use of CRL passed to help in the verification process. When libcurl is built with OpenSSL support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL check against all the elements of the certificate chain if a CRL file is passed.

This option makes sense only when used in combination with the ssl_verify_peer option.

A specific error code (is_ssl_crl_badfile) is defined with the option. It is returned when the SSL exchange fails because the CRL file cannot be loaded. A failure in certificate verification due to a revocation information found in the CRL does not trigger this specific error.

By default this option is not set and corresponds to CURLOPT_CRLFILE.

pub fn certinfo(&mut self, enable: bool) -> Result<(), Error>

Request SSL certificate information

Enable libcurl's certificate chain info gatherer. With this enabled, libcurl will extract lots of information and data about the certificates in the certificate chain used in the SSL connection.

By default this option is false and corresponds to CURLOPT_CERTINFO.

pub fn random_file<P: AsRef<Path>>(&mut self, p: P) -> Result<(), Error>

Specify a source for random data

The file will be used to read from to seed the random engine for SSL and more.

By default this option is not set and corresponds to CURLOPT_RANDOM_FILE.

pub fn egd_socket<P: AsRef<Path>>(&mut self, p: P) -> Result<(), Error>

Specify EGD socket path.

Indicates the path name to the Entropy Gathering Daemon socket. It will be used to seed the random engine for SSL.

By default this option is not set and corresponds to CURLOPT_EGDSOCKET.

pub fn ssl_cipher_list(&mut self, ciphers: &str) -> Result<(), Error>

Specify ciphers to use for TLS.

Holds the list of ciphers to use for the SSL connection. The list must be syntactically correct, it consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators but colons are normally used, !, - and + can be used as operators.

For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA', ´SHA1+DES´, 'TLSv1' and 'DEFAULT'. The default list is normally set when you compile OpenSSL.

You'll find more details about cipher lists on this URL:

https://www.openssl.org/docs/apps/ciphers.html

For NSS, valid examples of cipher lists include 'rsa_rc4_128_md5', ´rsa_aes_128_sha´, etc. With NSS you don't add/remove ciphers. If one uses this option then all known ciphers are disabled and only those passed in are enabled.

You'll find more details about the NSS cipher lists on this URL:

http://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives

By default this option is not set and corresponds to CURLOPT_SSL_CIPHER_LIST.

pub fn ssl_sessionid_cache(&mut self, enable: bool) -> Result<(), Error>

Enable or disable use of the SSL session-ID cache

By default all transfers are done using the cache enabled. While nothing ever should get hurt by attempting to reuse SSL session-IDs, there seem to be or have been broken SSL implementations in the wild that may require you to disable this in order for you to succeed.

This corresponds to the CURLOPT_SSL_SESSIONID_CACHE option.

pub fn ssl_options(&mut self, bits: &SslOpt) -> Result<(), Error>

Set SSL behavior options

Inform libcurl about SSL specific behaviors.

This corresponds to the CURLOPT_SSL_OPTIONS option.

pub fn time_condition_unmet(&mut self) -> Result<bool, Error>

Get info on unmet time conditional

Returns if the condition provided in the previous request didn't match

option is not supported

pub fn effective_url(&mut self) -> Result<Option<&str>, Error>

Get the last used URL

In cases when you've asked libcurl to follow redirects, it may not be the same value you set with url.

This methods corresponds to the CURLINFO_EFFECTIVE_URL option.

Returns Ok(None) if no effective url is listed or Err if an error happens or the underlying bytes aren't valid utf-8.

pub fn effective_url_bytes(&mut self) -> Result<Option<&[u8]>, Error>

Get the last used URL, in bytes

In cases when you've asked libcurl to follow redirects, it may not be the same value you set with url.

This methods corresponds to the CURLINFO_EFFECTIVE_URL option.

Returns Ok(None) if no effective url is listed or Err if an error happens or the underlying bytes aren't valid utf-8.

pub fn response_code(&mut self) -> Result<u32, Error>

Get the last response code

The stored value will be zero if no server response code has been received. Note that a proxy's CONNECT response should be read with http_connectcode and not this.

Corresponds to CURLINFO_RESPONSE_CODE and returns an error if this option is not supported.

pub fn http_connectcode(&mut self) -> Result<u32, Error>

Get the CONNECT response code

Returns the last received HTTP proxy response code to a CONNECT request. The returned value will be zero if no such response code was available.

Corresponds to CURLINFO_HTTP_CONNECTCODE and returns an error if this option is not supported.

pub fn filetime(&mut self) -> Result<Option<i64>, Error>

Get the remote time of the retrieved document

Returns the remote time of the retrieved document (in number of seconds since 1 Jan 1970 in the GMT/UTC time zone). If you get None, it can be because of many reasons (it might be unknown, the server might hide it or the server doesn't support the command that tells document time etc) and the time of the document is unknown.

Note that you must tell the server to collect this information before the transfer is made, by using the filetime method to or you will unconditionally get a None back.

This corresponds to CURLINFO_FILETIME and may return an error if the option is not supported

pub fn download_size(&mut self) -> Result<f64, Error>

Get the number of downloaded bytes

Returns the total amount of bytes that were downloaded. The amount is only for the latest transfer and will be reset again for each new transfer. This counts actual payload data, what's also commonly called body. All meta and header data are excluded and will not be counted in this number.

This corresponds to CURLINFO_SIZE_DOWNLOAD and may return an error if the option is not supported

pub fn content_length_download(&mut self) -> Result<f64, Error>

Get the content-length of the download

Returns the content-length of the download. This is the value read from the Content-Length: field

This corresponds to CURLINFO_CONTENT_LENGTH_DOWNLOAD and may return an error if the option is not supported

pub fn total_time(&mut self) -> Result<Duration, Error>

Get total time of previous transfer

Returns the total time for the previous transfer, including name resolving, TCP connect etc.

Corresponds to CURLINFO_TOTAL_TIME and may return an error if the option isn't supported.

pub fn namelookup_time(&mut self) -> Result<Duration, Error>

Get the name lookup time

Returns the total time from the start until the name resolving was completed.

Corresponds to CURLINFO_NAMELOOKUP_TIME and may return an error if the option isn't supported.

pub fn connect_time(&mut self) -> Result<Duration, Error>

Get the time until connect

Returns the total time from the start until the connection to the remote host (or proxy) was completed.

Corresponds to CURLINFO_CONNECT_TIME and may return an error if the option isn't supported.

pub fn appconnect_time(&mut self) -> Result<Duration, Error>

Get the time until the SSL/SSH handshake is completed

Returns the total time it took from the start until the SSL/SSH connect/handshake to the remote host was completed. This time is most often very near to the pretransfer_time time, except for cases such as HTTP pipelining where the pretransfer time can be delayed due to waits in line for the pipeline and more.

Corresponds to CURLINFO_APPCONNECT_TIME and may return an error if the option isn't supported.

pub fn pretransfer_time(&mut self) -> Result<Duration, Error>

Get the time until the file transfer start

Returns the total time it took from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. It does not involve the sending of the protocol- specific request that triggers a transfer.

Corresponds to CURLINFO_PRETRANSFER_TIME and may return an error if the option isn't supported.

pub fn starttransfer_time(&mut self) -> Result<Duration, Error>

Get the time until the first byte is received

Returns the total time it took from the start until the first byte is received by libcurl. This includes pretransfer_time and also the time the server needs to calculate the result.

Corresponds to CURLINFO_STARTTRANSFER_TIME and may return an error if the option isn't supported.

pub fn redirect_time(&mut self) -> Result<Duration, Error>

Get the time for all redirection steps

Returns the total time it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started. redirect_time contains the complete execution time for multiple redirections.

Corresponds to CURLINFO_REDIRECT_TIME and may return an error if the option isn't supported.

pub fn redirect_count(&mut self) -> Result<u32, Error>

Get the number of redirects

Corresponds to CURLINFO_REDIRECT_COUNT and may return an error if the option isn't supported.

pub fn redirect_url(&mut self) -> Result<Option<&str>, Error>

Get the URL a redirect would go to

Returns the URL a redirect would take you to if you would enable follow_location. This can come very handy if you think using the built-in libcurl redirect logic isn't good enough for you but you would still prefer to avoid implementing all the magic of figuring out the new URL.

Corresponds to CURLINFO_REDIRECT_URL and may return an error if the url isn't valid utf-8 or an error happens.

pub fn redirect_url_bytes(&mut self) -> Result<Option<&[u8]>, Error>

Get the URL a redirect would go to, in bytes

Returns the URL a redirect would take you to if you would enable follow_location. This can come very handy if you think using the built-in libcurl redirect logic isn't good enough for you but you would still prefer to avoid implementing all the magic of figuring out the new URL.

Corresponds to CURLINFO_REDIRECT_URL and may return an error.

pub fn header_size(&mut self) -> Result<u64, Error>

Get size of retrieved headers

Corresponds to CURLINFO_HEADER_SIZE and may return an error if the option isn't supported.

pub fn request_size(&mut self) -> Result<u64, Error>

Get size of sent request.

Corresponds to CURLINFO_REQUEST_SIZE and may return an error if the option isn't supported.

pub fn content_type(&mut self) -> Result<Option<&str>, Error>

Get Content-Type

Returns the content-type of the downloaded object. This is the value read from the Content-Type: field. If you get None, it means that the server didn't send a valid Content-Type header or that the protocol used doesn't support this.

Corresponds to CURLINFO_CONTENT_TYPE and may return an error if the option isn't supported.

pub fn content_type_bytes(&mut self) -> Result<Option<&[u8]>, Error>

Get Content-Type, in bytes

Returns the content-type of the downloaded object. This is the value read from the Content-Type: field. If you get None, it means that the server didn't send a valid Content-Type header or that the protocol used doesn't support this.

Corresponds to CURLINFO_CONTENT_TYPE and may return an error if the option isn't supported.

pub fn os_errno(&mut self) -> Result<i32, Error>

Get errno number from last connect failure.

Note that the value is only set on failure, it is not reset upon a successful operation. The number is OS and system specific.

Corresponds to CURLINFO_OS_ERRNO and may return an error if the option isn't supported.

pub fn primary_ip(&mut self) -> Result<Option<&str>, Error>

Get IP address of last connection.

Returns a string holding the IP address of the most recent connection done with this curl handle. This string may be IPv6 when that is enabled.

Corresponds to CURLINFO_PRIMARY_IP and may return an error if the option isn't supported.

pub fn primary_port(&mut self) -> Result<u16, Error>

Get the latest destination port number

Corresponds to CURLINFO_PRIMARY_PORT and may return an error if the option isn't supported.

pub fn local_ip(&mut self) -> Result<Option<&str>, Error>

Get local IP address of last connection

Returns a string holding the IP address of the local end of most recent connection done with this curl handle. This string may be IPv6 when that is enabled.

Corresponds to CURLINFO_LOCAL_IP and may return an error if the option isn't supported.

pub fn local_port(&mut self) -> Result<u16, Error>

Get the latest local port number

Corresponds to CURLINFO_LOCAL_PORT and may return an error if the option isn't supported.

pub fn cookies(&mut self) -> Result<List, Error>

Get all known cookies

Returns a linked-list of all cookies cURL knows (expired ones, too).

Corresponds to the CURLINFO_COOKIELIST option and may return an error if the option isn't supported.

pub fn pipewait(&mut self, wait: bool) -> Result<(), Error>

Wait for pipelining/multiplexing

Set wait to true to tell libcurl to prefer to wait for a connection to confirm or deny that it can do pipelining or multiplexing before continuing.

When about to perform a new transfer that allows pipelining or multiplexing, libcurl will check for existing connections to re-use and pipeline on. If no such connection exists it will immediately continue and create a fresh new connection to use.

By setting this option to true - and having pipelining(true, true) enabled for the multi handle this transfer is associated with - libcurl will instead wait for the connection to reveal if it is possible to pipeline/multiplex on before it continues. This enables libcurl to much better keep the number of connections to a minimum when using pipelining or multiplexing protocols.

The effect thus becomes that with this option set, libcurl prefers to wait and re-use an existing connection for pipelining rather than the opposite: prefer to open a new connection rather than waiting.

The waiting time is as long as it takes for the connection to get up and for libcurl to get the necessary response back that informs it about its protocol and support level.

This corresponds to the CURLOPT_PIPEWAIT option.

pub fn perform(&self) -> Result<(), Error>

After options have been set, this will perform the transfer described by the options.

This performs the request in a synchronous fashion. This can be used multiple times for one easy handle and libcurl will attempt to re-use the same connection for all transfers.

This method will preserve all options configured in this handle for the next request, and if that is not desired then the options can be manually reset or the reset method can be called.

Note that this method takes &self, which is quite important! This allows applications to close over the handle in various callbacks to call methods like unpause_write and unpause_read while a transfer is in progress.

pub fn unpause_read(&self) -> Result<(), Error>

Unpause reading on a connection.

Using this function, you can explicitly unpause a connection that was previously paused.

A connection can be paused by letting the read or the write callbacks return ReadError::Pause or WriteError::Pause.

To unpause, you may for example call this from the progress callback which gets called at least once per second, even if the connection is paused.

The chance is high that you will get your write callback called before this function returns.

pub fn unpause_write(&self) -> Result<(), Error>

Unpause writing on a connection.

Using this function, you can explicitly unpause a connection that was previously paused.

A connection can be paused by letting the read or the write callbacks return ReadError::Pause or WriteError::Pause. A write callback that returns pause signals to the library that it couldn't take care of any data at all, and that data will then be delivered again to the callback when the writing is later unpaused.

To unpause, you may for example call this from the progress callback which gets called at least once per second, even if the connection is paused.

pub fn url_encode(&mut self, s: &[u8]) -> String

URL encodes a string s

pub fn url_decode(&mut self, s: &str) -> Vec<u8>

URL decodes a string s, returning None if it fails

pub fn recv(&mut self, data: &mut [u8]) -> Result<usize, Error>

Receives data from a connected socket.

Only useful after a successful perform with the connect_only option set as well.

pub fn send(&mut self, data: &[u8]) -> Result<usize, Error>

Sends data over the connected socket.

Only useful after a successful perform with the connect_only option set as well.

pub fn raw(&self) -> *mut CURL

Get a pointer to the raw underlying CURL handle.

pub fn take_error_buf(&self) -> Option<String>

Returns the contents of the internal error buffer, if available.

When an easy handle is created it configured the CURLOPT_ERRORBUFFER parameter and instructs libcurl to store more error information into a buffer for better error messages and better debugging. The contents of that buffer are automatically coupled with all errors for methods on this type, but if manually invoking APIs the contents will need to be extracted with this method.

Put another way, you probably don't need this, you're probably already getting nice error messages!

This function will clear the internal buffer, so this is an operation that mutates the handle internally.

Trait Implementations

impl<H> Drop for Easy2<H>

fn drop(&mut self)

Executes the destructor for this type.

impl<H: Debug> Debug for Easy2<H>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.