Repository files navigation

libcurl bindings for Rust

use std::io::{stdout,Write};use curl::easy::Easy;// Print a web page onto stdoutfnmain(){letmut easy =Easy::new();    easy.url("https://www.rust-lang.org/").unwrap();    easy.write_function(|data|{stdout().write_all(data).unwrap();Ok(data.len())}).unwrap();    easy.perform().unwrap();println!("{}", easy.response_code().unwrap());}

use curl::easy::Easy;// Capture output into a local `Vec`.fnmain(){letmut dst =Vec::new();letmut easy =Easy::new();    easy.url("https://www.rust-lang.org/").unwrap();letmut transfer = easy.transfer();    transfer.write_function(|data|{        dst.extend_from_slice(data);Ok(data.len())}).unwrap();    transfer.perform().unwrap();}

Theput andpost methods onEasy can configure the method of the HTTPrequest, and thenread_function can be used to specify how data is filled in.This interface works particularly well with types that implementRead.

use std::io::Read;use curl::easy::Easy;fnmain(){letmut data ="this is the body".as_bytes();letmut easy =Easy::new();    easy.url("http://www.example.com/upload").unwrap();    easy.post(true).unwrap();    easy.post_field_size(data.len()asu64).unwrap();letmut transfer = easy.transfer();    transfer.read_function(|buf|{Ok(data.read(buf).unwrap_or(0))}).unwrap();    transfer.perform().unwrap();}

Custom headers can be specified as part of the request:

use curl::easy::{Easy,List};fnmain(){letmut easy =Easy::new();    easy.url("http://www.example.com").unwrap();letmut list =List::new();    list.append("Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==").unwrap();    easy.http_headers(list).unwrap();    easy.perform().unwrap();}

The handle can be re-used across multiple requests. Curl will attempt tokeep the connections alive.

use curl::easy::Easy;fnmain(){letmut handle =Easy::new();    handle.url("http://www.example.com/foo").unwrap();    handle.perform().unwrap();    handle.url("http://www.example.com/bar").unwrap();    handle.perform().unwrap();}

The libcurl library provides support for sending multiple requestssimultaneously through the "multi" interface. This is currently bound in themulti module of this crate and provides the ability to execute multipletransfers simultaneously. For more information, see that module.

By default, this crate will attempt to dynamically link to the system-widelibcurl and the system-wide SSL library. Some of this behavior can be customizedwith various Cargo features:

• ssl: Enable SSL/TLS support using the platform-default TLS backend. On Windows this isSchannel, on macOSSecure Transport, andOpenSSL (or equivalent) on all other platforms. Enabled by default.

• rustls Enable SSL/TLS support viaRustls, a well-received alternative TLS backend written in Rust. Rustls is always statically linked. Disabled by default.

  Note that Rustls support is experimental within Curl itself and may have significant bugs, so we don't offer any sort of stability guarantee with this feature.

• http2: Enable HTTP/2 support via libnghttp2. Disabled by default.

• static-curl: Use a bundled libcurl version and statically link to it. Disabled by default.

• static-ssl: Use a bundled OpenSSL version and statically link to it. Only applies on platforms that use OpenSSL. Disabled by default.

• spnego: Enable SPNEGO support. Disabled by default.

• upkeep_7_62_0: Enable curl_easy_upkeep() support, introduced in curl 7.62.0. Disabled by default.

• poll_7_68_0: Enable curl_multi_poll()/curl_multi_wakeup() support, requires curl 7.68.0 or later. Disabled by default.

• ntlm: Enable NTLM support in curl. Disabled by default.

• windows-static-ssl: Enable Openssl support on Windows via the static build provided by vcpkg. Incompatible withssl (use--no-default-features). Disabled by default.

  Note that to install openssl on windows via vcpkg the following commands needs to be ran:

  git clone https://github.com/microsoft/vcpkgcd vcpkg./bootstrap-vcpkg.bat -disableMetrics./vcpkg.exe integrate install./vcpkg.exe install openssl:x64-windows-static-md

The bindings have been developed using curl version 7.24.0. They shouldwork with any newer version of curl and possibly with older versions,but this has not been tested.

If you encounter the following error message:

  [77] Problem with the SSL CA cert (path? access rights?)

That means most likely, that curl was linked againstlibcurl-nss.so due toinstalled libcurl NSS development files, and that the required librarylibnsspem.so is missing. See also the curl man page: "If curl is builtagainst the NSS SSL library, the NSS PEM PKCS#11 module (libnsspem.so) needs to be available for this option to work properly."

In order to avoid this failure you can either

• install the missing library (e.g. Debian:nss-plugin-pem), or
• remove the libcurl NSS development files (e.g. Debian:libcurl4-nss-dev) andrebuild curl-rust.

Thecurl-rust crate is licensed under the MIT license, seeLICENSE for moredetails.