nyquest_preset/
lib.rs

1//! Nyquest preset configuration with up-to-date rich-featured backends.
2//!
3//! `nyquest-preset` is the official, default backend provider of [`nyquest`] that integrates
4//! [`nyquest-backend-winrt`], [`nyquest-backend-nsurlsession`] and [`nyquest-backend-curl`]
5//! into a uniform interface. The only exposed APIs are the [`register`] function and the
6//! [`Backend`] type of the underlying backend.
7//!
8//! This crate is intended to be consumed by end application users. Since there can be only one
9//! backend registered as the global default, library authors in general are not recommended to
10//! declare this crate as a dependency. Libraries should use [`nyquest`] instead.
11//!
12//! ## Quick Start
13//!
14//! Add the following at your program startup:
15//! ```no_run
16//! nyquest_backend::register();
17//! ```
18//! Based on the target platform, a [`nyquest`] backend will be registered as the default. Refer to
19//! the documentation of [`nyquest`] for usages.
20//!
21//! ## Platform Support
22//!
23//! `nyquest-preset` uses `cfg` to select the appropriate backend for the target platform.
24//!
25//! - `windows`: [`nyquest-backend-winrt`]
26//! - `target_vendor = "apple"`: [`nyquest-backend-nsurlsession`]
27//! - others: [`nyquest-backend-curl`]
28//!
29//! Refer to the backends' documentation for specific platform requirements.
30//!
31//! ## Features
32//!
33//! - `async`: Enable async support for backends and [`nyquest`].
34//! - `async-stream`: Enable async support and streaming upload/download for backends and
35//!   [`nyquest`].
36//! - `blocking`: Enable blocking support for backends and [`nyquest`].
37//! - `blocking-stream`: Enable blocking support and streaming upload/download for backends and
38//!   [`nyquest`].
39//! - `multipart`: Enable multipart form support for backends and [`nyquest`].
40//!
41//! Refer to the backends' documentation for more optional features. For example, enable
42//! `charset-defaults` for [`nyquest-backend-curl`] to perform encoding conversion automatically
43//! when the response has an encoding other than UTF-8.
44//!
45//! [`nyquest-backend-winrt`]: https://docs.rs/nyquest-backend-winrt
46//! [`nyquest-backend-nsurlsession`]: https://docs.rs/nyquest-backend-nsurlsession
47//! [`nyquest-backend-curl`]: https://docs.rs/nyquest-backend-curl
48//!
49mod sys;
50
51pub use nyquest;
52
53/// Initialize and register the underlying backend as global default.
54pub use sys::register;
55#[doc(no_inline)]
56pub use sys::Backend;
57
58#[cfg(feature = "auto-register")]
59ctor::declarative::ctor! {
60    #[ctor]
61    fn auto_register() {
62        register();
63    }
64}