apns_h2/
lib.rs

1//! # apns-h2
2//!
3//! `apns-h2` is an asynchronous client to Apple push notification service. It
4//! provides a type-safe way to generate correct requests, mapping responses into
5//! corresponding types. The client supports both, certificate and token based
6//! authentication.
7//!
8//! To create a connection it is required to have either a PKCS12 database file
9//! including a valid certificate and private key with a password for unlocking
10//! it, or a private key in PKCS8 PEM format with the corresponding team and key
11//! ids. All of these should be available from Xcode or your Apple developer
12//! account.
13//!
14//! ## Payload
15//!
16//! Building the notification payload should be done with the [DefaultNotificationBuilder](request/notification/struct.DefaultNotificationBuilder.html) for most use-cases.
17//! There is also the [WebNotificationBuilder](request/notification/struct.WebNotificationBuilder.html) in the case you need to send notifications to safari
18//!
19//! The payload generated by the builder [can hold a custom data
20//! section](request/payload/struct.Payload.html#method.add_custom_data),
21//! defined by a selected root key. Any data using `#[derive(Serialize)]` from
22//! [Serde](https://serde.rs/) works, allowing usage of type-safe structs or
23//! dynamic hashmaps to generate the custom data.
24//!
25//! ## Client
26//!
27//! The [asynchronous client](client/struct.Client.html), works either with
28//! [certificate](client/struct.Client.html#method.certificate) or
29//! [token](client/struct.Client.html#method.token) authentication.
30//!
31//! ## Example sending a plain notification using token authentication:
32//!
33//! ```no_run
34//! # use apns_h2::{DefaultNotificationBuilder, NotificationBuilder, Client, ClientConfig, Endpoint};
35//! # use std::fs::File;
36//! # #[tokio::main]
37//! # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
38//! let mut builder = DefaultNotificationBuilder::new()
39//!     .set_body("Hi there")
40//!     .set_badge(420)
41//!     .set_category("cat1")
42//!     .set_sound("ping.flac");
43//!
44//! let payload = builder.build("device-token-from-the-user", Default::default());
45//! let mut file = File::open("/path/to/private_key.p8")?;
46//!
47//! let client = Client::token(
48//!     &mut file,
49//!     "KEY_ID",
50//!     "TEAM_ID",
51//!     ClientConfig::default()).unwrap();
52//!
53//! let response = client.send(payload).await?;
54//! println!("Sent: {:?}", response);
55//! # Ok(())
56//! # }
57//! ```
58//!
59//! ## Example sending a silent notification with custom data using certificate authentication:
60//!
61//! ```no_run
62//! #[macro_use] extern crate serde;
63//! # #[cfg(all(feature = "openssl", not(feature = "aws-lc-rs")))]
64//! # {
65//!
66//! use apns_h2::{
67//!     Client, ClientConfig, Endpoint, DefaultNotificationBuilder, NotificationBuilder, NotificationOptions,
68//!     Priority,
69//! };
70//! use std::fs::File;
71//!
72//! #[derive(Serialize, Debug)]
73//! struct CorporateData {
74//!     tracking_code: &'static str,
75//!     is_paying_user: bool,
76//! }
77//!
78//! #[tokio::main]
79//! async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
80//!     let tracking_data = CorporateData {
81//!         tracking_code: "999-212-UF-NSA",
82//!         is_paying_user: false,
83//!     };
84//!
85//!     let mut payload = DefaultNotificationBuilder::new()
86//!         .set_content_available()
87//!         .build("device-token-from-the-user",
88//!         NotificationOptions {
89//!             apns_priority: Some(Priority::Normal),
90//!             ..Default::default()
91//!         },
92//!     );
93//!     payload.add_custom_data("apns_gmbh", &tracking_data)?;
94//!
95//!     let mut file = File::open("/path/to/cert_db.p12")?;
96//!
97//!     let client = Client::certificate(
98//!         &mut file,
99//!         "Correct Horse Battery Stable",
100//!         ClientConfig::default())?;
101//!
102//!     let response = client.send(payload).await?;
103//!     println!("Sent: {:?}", response);
104//!
105//!     Ok(())
106//! }
107//! # }
108//! ```
109#![warn(clippy::unwrap_used)]
110
111#[cfg(not(any(feature = "openssl", feature = "aws-lc-rs")))]
112compile_error!("either feature \"openssl\" or feature \"ring\" has to be enabled");
113
114#[macro_use]
115extern crate serde;
116
117#[allow(unused_imports)]
118#[macro_use]
119extern crate serde_json;
120
121pub mod client;
122pub mod error;
123#[cfg(feature = "aws-lc-rs")]
124mod pkcs12;
125pub mod request;
126pub mod response;
127mod signer;
128
129pub use crate::request::notification::{
130    CollapseId, DefaultNotificationBuilder, NotificationBuilder, NotificationOptions, Priority, PushType,
131    WebNotificationBuilder, WebPushAlert,
132};
133
134pub use crate::request::payload::InterruptionLevel;
135
136pub use crate::response::{ErrorBody, ErrorReason, Response};
137
138pub use crate::client::{Client, ClientConfig, Endpoint};
139
140pub use crate::error::Error;
apns_h2/lib.rs

apns_h2/
lib.rs
