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