aws_sdk_iot/lib.rs
1#![allow(deprecated)]
2#![allow(unknown_lints)]
3#![allow(clippy::module_inception)]
4#![allow(clippy::upper_case_acronyms)]
5#![allow(clippy::large_enum_variant)]
6#![allow(clippy::wrong_self_convention)]
7#![allow(clippy::should_implement_trait)]
8#![allow(clippy::disallowed_names)]
9#![allow(clippy::vec_init_then_push)]
10#![allow(clippy::type_complexity)]
11#![allow(clippy::needless_return)]
12#![allow(clippy::derive_partial_eq_without_eq)]
13#![allow(clippy::result_large_err)]
14#![allow(clippy::unnecessary_map_on_constructor)]
15#![allow(rustdoc::bare_urls)]
16#![allow(rustdoc::redundant_explicit_links)]
17#![allow(rustdoc::invalid_html_tags)]
18#![forbid(unsafe_code)]
19#![warn(missing_docs)]
20#![cfg_attr(docsrs, feature(doc_auto_cfg))]
21//! IoT provides secure, bi-directional communication between Internet-connected devices (such as sensors, actuators, embedded devices, or smart appliances) and the Amazon Web Services cloud. You can discover your custom IoT-Data endpoint to communicate with, configure rules for data processing and integration with other services, organize resources associated with each device (Registry), configure logging, and create and manage policies and credentials to authenticate devices.
22//!
23//! The service endpoints that expose this API are listed in [Amazon Web Services IoT Core Endpoints and Quotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html). You must use the endpoint for the region that has the resources you want to access.
24//!
25//! The service name used by [Amazon Web Services Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) to sign the request is: _execute-api_.
26//!
27//! For more information about how IoT works, see the [Developer Guide](https://docs.aws.amazon.com/iot/latest/developerguide/aws-iot-how-it-works.html).
28//!
29//! For information about how to use the credentials provider for IoT, see [Authorizing Direct Calls to Amazon Web Services Services](https://docs.aws.amazon.com/iot/latest/developerguide/authorizing-direct-aws.html).
30//!
31//! ## Getting Started
32//!
33//! > Examples are available for many services and operations, check out the
34//! > [examples folder in GitHub](https://github.com/awslabs/aws-sdk-rust/tree/main/examples).
35//!
36//! The SDK provides one crate per AWS service. You must add [Tokio](https://crates.io/crates/tokio)
37//! as a dependency within your Rust project to execute asynchronous code. To add `aws-sdk-iot` to
38//! your project, add the following to your **Cargo.toml** file:
39//!
40//! ```toml
41//! [dependencies]
42//! aws-config = { version = "1.1.7", features = ["behavior-version-latest"] }
43//! aws-sdk-iot = "1.94.0"
44//! tokio = { version = "1", features = ["full"] }
45//! ```
46//!
47//! Then in code, a client can be created with the following:
48//!
49//! ```rust,no_run
50//! use aws_sdk_iot as iot;
51//!
52//! #[::tokio::main]
53//! async fn main() -> Result<(), iot::Error> {
54//! let config = aws_config::load_from_env().await;
55//! let client = aws_sdk_iot::Client::new(&config);
56//!
57//! // ... make some calls with the client
58//!
59//! Ok(())
60//! }
61//! ```
62//!
63//! See the [client documentation](https://docs.rs/aws-sdk-iot/latest/aws_sdk_iot/client/struct.Client.html)
64//! for information on what calls can be made, and the inputs and outputs for each of those calls.
65//!
66//! ## Using the SDK
67//!
68//! Until the SDK is released, we will be adding information about using the SDK to the
69//! [Developer Guide](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/welcome.html). Feel free to suggest
70//! additional sections for the guide by opening an issue and describing what you are trying to do.
71//!
72//! ## Getting Help
73//!
74//! * [GitHub discussions](https://github.com/awslabs/aws-sdk-rust/discussions) - For ideas, RFCs & general questions
75//! * [GitHub issues](https://github.com/awslabs/aws-sdk-rust/issues/new/choose) - For bug reports & feature requests
76//! * [Generated Docs (latest version)](https://awslabs.github.io/aws-sdk-rust/)
77//! * [Usage examples](https://github.com/awslabs/aws-sdk-rust/tree/main/examples)
78//!
79//!
80//! # Crate Organization
81//!
82//! The entry point for most customers will be [`Client`], which exposes one method for each API
83//! offered by AWS IoT. The return value of each of these methods is a "fluent builder",
84//! where the different inputs for that API are added by builder-style function call chaining,
85//! followed by calling `send()` to get a [`Future`](std::future::Future) that will result in
86//! either a successful output or a [`SdkError`](crate::error::SdkError).
87//!
88//! Some of these API inputs may be structs or enums to provide more complex structured information.
89//! These structs and enums live in [`types`](crate::types). There are some simpler types for
90//! representing data such as date times or binary blobs that live in [`primitives`](crate::primitives).
91//!
92//! All types required to configure a client via the [`Config`](crate::Config) struct live
93//! in [`config`](crate::config).
94//!
95//! The [`operation`](crate::operation) module has a submodule for every API, and in each submodule
96//! is the input, output, and error type for that API, as well as builders to construct each of those.
97//!
98//! There is a top-level [`Error`](crate::Error) type that encompasses all the errors that the
99//! client can return. Any other error type can be converted to this `Error` type via the
100//! [`From`](std::convert::From) trait.
101//!
102//! The other modules within this crate are not required for normal usage.
103
104// Code generated by software.amazon.smithy.rust.codegen.smithy-rs. DO NOT EDIT.
105pub use error_meta::Error;
106
107#[doc(inline)]
108pub use config::Config;
109
110/// Client for calling AWS IoT.
111/// ## Constructing a `Client`
112///
113/// A [`Config`] is required to construct a client. For most use cases, the [`aws-config`]
114/// crate should be used to automatically resolve this config using
115/// [`aws_config::load_from_env()`], since this will resolve an [`SdkConfig`] which can be shared
116/// across multiple different AWS SDK clients. This config resolution process can be customized
117/// by calling [`aws_config::from_env()`] instead, which returns a [`ConfigLoader`] that uses
118/// the [builder pattern] to customize the default config.
119///
120/// In the simplest case, creating a client looks as follows:
121/// ```rust,no_run
122/// # async fn wrapper() {
123/// let config = aws_config::load_from_env().await;
124/// let client = aws_sdk_iot::Client::new(&config);
125/// # }
126/// ```
127///
128/// Occasionally, SDKs may have additional service-specific values that can be set on the [`Config`] that
129/// is absent from [`SdkConfig`], or slightly different settings for a specific client may be desired.
130/// The [`Builder`](crate::config::Builder) struct implements `From<&SdkConfig>`, so setting these specific settings can be
131/// done as follows:
132///
133/// ```rust,no_run
134/// # async fn wrapper() {
135/// let sdk_config = ::aws_config::load_from_env().await;
136/// let config = aws_sdk_iot::config::Builder::from(&sdk_config)
137/// # /*
138/// .some_service_specific_setting("value")
139/// # */
140/// .build();
141/// # }
142/// ```
143///
144/// See the [`aws-config` docs] and [`Config`] for more information on customizing configuration.
145///
146/// _Note:_ Client construction is expensive due to connection thread pool initialization, and should
147/// be done once at application start-up.
148///
149/// [`Config`]: crate::Config
150/// [`ConfigLoader`]: https://docs.rs/aws-config/*/aws_config/struct.ConfigLoader.html
151/// [`SdkConfig`]: https://docs.rs/aws-config/*/aws_config/struct.SdkConfig.html
152/// [`aws-config` docs]: https://docs.rs/aws-config/*
153/// [`aws-config`]: https://crates.io/crates/aws-config
154/// [`aws_config::from_env()`]: https://docs.rs/aws-config/*/aws_config/fn.from_env.html
155/// [`aws_config::load_from_env()`]: https://docs.rs/aws-config/*/aws_config/fn.load_from_env.html
156/// [builder pattern]: https://rust-lang.github.io/api-guidelines/type-safety.html#builders-enable-construction-of-complex-values-c-builder
157/// # Using the `Client`
158///
159/// A client has a function for every operation that can be performed by the service.
160/// For example, the [`AcceptCertificateTransfer`](crate::operation::accept_certificate_transfer) operation has
161/// a [`Client::accept_certificate_transfer`], function which returns a builder for that operation.
162/// The fluent builder ultimately has a `send()` function that returns an async future that
163/// returns a result, as illustrated below:
164///
165/// ```rust,ignore
166/// let result = client.accept_certificate_transfer()
167/// .certificate_id("example")
168/// .send()
169/// .await;
170/// ```
171///
172/// The underlying HTTP requests that get made by this can be modified with the `customize_operation`
173/// function on the fluent builder. See the [`customize`](crate::client::customize) module for more
174/// information.
175pub mod client;
176
177/// Configuration for AWS IoT.
178pub mod config;
179
180/// Common errors and error handling utilities.
181pub mod error;
182
183mod error_meta;
184
185/// Information about this crate.
186pub mod meta;
187
188/// All operations that this crate can perform.
189pub mod operation;
190
191/// Primitives such as `Blob` or `DateTime` used by other types.
192pub mod primitives;
193
194/// Data structures used by operation inputs/outputs.
195pub mod types;
196
197pub(crate) mod client_idempotency_token;
198
199mod idempotency_token;
200
201pub(crate) mod protocol_serde;
202
203mod sdk_feature_tracker;
204
205mod serialization_settings;
206
207mod endpoint_lib;
208
209mod lens;
210
211mod json_errors;
212
213mod serde_util;
214
215#[doc(inline)]
216pub use client::Client;