cue_sdk/
lib.rs

1//!  cue-sdk - A safe wrapper for the Corsair iCUE SDK.
2//!
3//! cue-sdk provides core functionality for interfacing with the
4//! Corsair iCUE SDK, through the [cue-sdk-sys](https://crates.io/crates/cue-sdk-sys) crate.
5//!
6//! # Quick Start
7//!
8//! Make sure you set the required environment variables for the [cue-sdk-sys](https://crates.io/crates/cue-sdk-sys)
9//! dependency crate.
10//!
11//! If you need the binaries, the easiest place to get them is on the [Github Releases Page](https://github.com/CorsairOfficial/cue-sdk).
12//! Since we can't build them from scratch (not open source) you have to get them yourself.
13//!
14//! This version of the crate is built against version [3.0.55](https://github.com/CorsairOfficial/cue-sdk/releases/tag/v3.0.355)
15//! of the iCUE SDK.
16//!
17//! # Example Code
18//!
19//! ```
20//! use cue_sdk::led::LedColor;
21//! use cue_sdk::initialize;
22//! let sdk = initialize()
23//!     .expect("failed to initialize sdk");
24//! let mut  devices = sdk.get_all_devices().expect("failed to get all devices");
25//! let new_color = LedColor { red: 200, green: 20, blue: 165 };
26//! for d in &mut devices {
27//!     //print some info
28//!     println!("Device: {:?} at index {:?} has led count: ${:?}",
29//!         d.device_info.model, d.device_index, d.leds.len());
30//!
31//!     // set the first led in every device to our `new_color` color
32//!     d.leds.first_mut().unwrap().update_color_buffer(new_color);
33//! }
34//! //flush the colors buffer (send to device hardware)
35//! sdk.flush_led_colors_update_buffer_sync()
36//!     .expect("failed to flush led buffer");
37//! ```
38//!
39//! You can note from the following example, most "write" operations can fail
40//! for a variety of reasons including but not limited to:
41//!
42//! - device state changes (devices have been unplugged/plugged in)
43//! - ffi interfacing (pointer derefs, etc) fail due to undocumented breaking changes in the iCUE SDK,
44//! or a bug in the crate code
45//! - another client has requested exclusive access
46//!
47//! # Examples
48//!
49//! For additional examples see the [example code](https://github.com/scottroemeschke/cue-sdk-rust)
50//! and run examples with `cargo run --example {example_name}`.
51//!
52//!
53#[macro_use]
54extern crate failure_derive;
55#[macro_use]
56extern crate num_derive;
57
58#[cfg(test)]
59#[macro_use]
60extern crate strum_macros;
61
62pub(crate) mod internal;
63
64pub mod device;
65pub mod errors;
66pub mod event;
67pub mod initialization;
68pub mod key;
69pub mod led;
70pub mod property;
71pub mod sdk;
72
73use crate::sdk::CueSdkClient;
74use initialization::HandshakeError;
75
76/// This is the single and only way currently to initialize the SDK.
77///
78/// This method can fail for a variety of reasons, the most likely being
79/// that the Corsair iCUE software isn't running on the target machine.
80///
81/// See [`HandshakeError`] error, for more details.
82///
83/// We recommend you keep a single instance of the SDK for your application,
84/// as the iCUE SDK does not expect multiple handshakes.
85///
86pub fn initialize() -> Result<CueSdkClient, HandshakeError> {
87    CueSdkClient::initialize()
88}
cue_sdk/lib.rs

cue_sdk/
lib.rs
