vendor/curl/README.md

   1 # curl-rust
   2
   3 [libcurl] bindings for Rust
   4
   5 [![Latest Version](https://img.shields.io/crates/v/curl.svg)](https://crates.io/crates/curl)
   6 [![Documentation](https://docs.rs/curl/badge.svg)](https://docs.rs/curl)
   7 [![License](https://img.shields.io/github/license/alexcrichton/curl-rust.svg)](LICENSE)
   8 [![Build](https://github.com/alexcrichton/curl-rust/workflows/CI/badge.svg)](https://github.com/alexcrichton/curl-rust/actions)
   9
  10 ## Quick Start
  11
  12 ```rust
  13 use std::io::{stdout, Write};
  14
  15 use curl::easy::Easy;
  16
  17 // Print a web page onto stdout
  18 fn main() {
  19     let mut easy = Easy::new();
  20     easy.url("https://www.rust-lang.org/").unwrap();
  21     easy.write_function(|data| {
  22         stdout().write_all(data).unwrap();
  23         Ok(data.len())
  24     }).unwrap();
  25     easy.perform().unwrap();
  26
  27     println!("{}", easy.response_code().unwrap());
  28 }
  29 ```
  30
  31 ```rust
  32 use curl::easy::Easy;
  33
  34 // Capture output into a local `Vec`.
  35 fn main() {
  36     let mut dst = Vec::new();
  37     let mut easy = Easy::new();
  38     easy.url("https://www.rust-lang.org/").unwrap();
  39
  40     let mut transfer = easy.transfer();
  41     transfer.write_function(|data| {
  42         dst.extend_from_slice(data);
  43         Ok(data.len())
  44     }).unwrap();
  45     transfer.perform().unwrap();
  46 }
  47 ```
  48
  49 ## Post / Put requests
  50
  51 The `put` and `post` methods on `Easy` can configure the method of the HTTP
  52 request, and then `read_function` can be used to specify how data is filled in.
  53 This interface works particularly well with types that implement `Read`.
  54
  55 ```rust,no_run
  56 use std::io::Read;
  57 use curl::easy::Easy;
  58
  59 fn main() {
  60     let mut data = "this is the body".as_bytes();
  61
  62     let mut easy = Easy::new();
  63     easy.url("http://www.example.com/upload").unwrap();
  64     easy.post(true).unwrap();
  65     easy.post_field_size(data.len() as u64).unwrap();
  66
  67     let mut transfer = easy.transfer();
  68     transfer.read_function(|buf| {
  69         Ok(data.read(buf).unwrap_or(0))
  70     }).unwrap();
  71     transfer.perform().unwrap();
  72 }
  73 ```
  74
  75 ## Custom headers
  76
  77 Custom headers can be specified as part of the request:
  78
  79 ```rust,no_run
  80 use curl::easy::{Easy, List};
  81
  82 fn main() {
  83     let mut easy = Easy::new();
  84     easy.url("http://www.example.com").unwrap();
  85
  86     let mut list = List::new();
  87     list.append("Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==").unwrap();
  88     easy.http_headers(list).unwrap();
  89     easy.perform().unwrap();
  90 }
  91 ```
  92
  93 ## Keep alive
  94
  95 The handle can be re-used across multiple requests. Curl will attempt to
  96 keep the connections alive.
  97
  98 ```rust,no_run
  99 use curl::easy::Easy;
 100
 101 fn main() {
 102     let mut handle = Easy::new();
 103
 104     handle.url("http://www.example.com/foo").unwrap();
 105     handle.perform().unwrap();
 106
 107     handle.url("http://www.example.com/bar").unwrap();
 108     handle.perform().unwrap();
 109 }
 110 ```
 111
 112 ## Multiple requests
 113
 114 The libcurl library provides support for sending multiple requests
 115 simultaneously through the "multi" interface. This is currently bound in the
 116 `multi` module of this crate and provides the ability to execute multiple
 117 transfers simultaneously. For more information, see that module.
 118
 119 ## Building
 120
 121 By default, this crate will attempt to dynamically link to the system-wide
 122 libcurl and the system-wide SSL library. Some of this behavior can be customized
 123 with various Cargo features:
 124
 125 - `ssl`: Enable SSL/TLS support using the platform-default TLS backend. On Windows this is [Schannel], on macOS [Secure Transport], and [OpenSSL] (or equivalent) on all other platforms.  Enabled by default.
 126 - `mesalink`: Enable SSL/TLS support via [MesaLink], an alternative TLS backend written in Rust based on [Rustls]. MesaLink is always statically linked. Disabled by default.
 127 - `http2`: Enable HTTP/2 support via libnghttp2. Disabled by default.
 128 - `static-curl`: Use a bundled libcurl version and statically link to it. Disabled by default.
 129 - `static-ssl`: Use a bundled OpenSSL version and statically link to it. Only applies on platforms that use OpenSSL. Disabled by default.
 130 - `spnego`: Enable SPNEGO support. Disabled by default.
 131 - `upkeep_7_62_0`: Enable curl_easy_upkeep() support, introduced in curl 7.62.0. Disabled by default.
 132
 133 ## Version Support
 134
 135 The bindings have been developed using curl version 7.24.0. They should
 136 work with any newer version of curl and possibly with older versions,
 137 but this has not been tested.
 138
 139 ## Troubleshooting
 140
 141 ### Curl built against the NSS SSL library
 142
 143 If you encounter the following error message:
 144
 145 ```
 146   [77] Problem with the SSL CA cert (path? access rights?)
 147 ```
 148
 149 That means most likely, that curl was linked against `libcurl-nss.so` due to
 150 installed libcurl NSS development files, and that the required library
 151 `libnsspem.so` is missing. See also the curl man page: "If curl is built
 152 against the NSS SSL library, the NSS PEM PKCS#11 module (`libnsspem.so`) needs to be available for this option to work properly."
 153
 154 In order to avoid this failure you can either
 155
 156  * install the missing library (e.g. Debian: `nss-plugin-pem`), or
 157  * remove the libcurl NSS development files (e.g. Debian: `libcurl4-nss-dev`) and
 158    rebuild curl-rust.
 159
 160 ## License
 161
 162 The `curl-rust` crate is licensed under the MIT license, see [`LICENSE`](LICENSE) for more
 163 details.
 164
 165
 166 [libcurl]: https://curl.haxx.se/libcurl/
 167 [MesaLink]: https://mesalink.io/
 168 [OpenSSL]: https://www.openssl.org/
 169 [Rustls]: https://github.com/ctz/rustls
 170 [Schannel]: https://docs.microsoft.com/en-us/windows/win32/com/schannel
 171 [Secure Transport]: https://developer.apple.com/documentation/security/secure_transport