Crate curl

source
Expand description

Rust bindings to the libcurl C library

This crate contains bindings for an HTTP/HTTPS client which is powered by libcurl, the same library behind the curl command line tool. The API currently closely matches that of libcurl itself, except that a Rustic layer of safety is applied on top.

§The “Easy” API

The easiest way to send a request is to use the Easy api which corresponds to CURL in libcurl. This handle supports a wide variety of options and can be used to make a single blocking request in a thread. Callbacks can be specified to deal with data as it arrives and a handle can be reused to cache connections and such.

use std::io::{stdout, Write};

use curl::easy::Easy;

// Write the contents of rust-lang.org to stdout
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();

§What about multiple concurrent HTTP requests?

One option you have currently is to send multiple requests in multiple threads, but otherwise libcurl has a “multi” interface for doing this operation. Initial bindings of this interface can be found in the multi module, but feedback is welcome!

§Where does libcurl come from?

This crate links to the curl-sys crate which is in turn responsible for acquiring and linking to the libcurl library. Currently this crate will build libcurl from source if one is not already detected on the system.

There is a large number of releases for libcurl, all with different sets of capabilities. Robust programs may wish to inspect Version::get() to test what features are implemented in the linked build of libcurl at runtime.

§Initialization

The underlying libcurl library must be initialized before use and has certain requirements on how this is done. Check the documentation for init for more details.

Modules§

  • easy
    Bindings to the “easy” libcurl API.
  • multi
    Multi - initiating multiple requests simultaneously

Structs§

  • Error
    An error returned from various “easy” operations.
  • FormError
    An error from “form add” operations.
  • MultiError
    An error from “multi” operations.
  • Protocols
    An iterator over the list of protocols a version supports.
  • ShareError
    An error returned from “share” operations.
  • Version
    Version information about libcurl and the capabilities that it supports.

Functions§

  • init
    Initializes the underlying libcurl library.