diff options
| -rw-r--r-- | niri-ipc/src/lib.rs | 20 | ||||
| -rw-r--r-- | niri-ipc/src/state.rs | 6 |
2 files changed, 26 insertions, 0 deletions
diff --git a/niri-ipc/src/lib.rs b/niri-ipc/src/lib.rs index 3ef74400..bf394a50 100644 --- a/niri-ipc/src/lib.rs +++ b/niri-ipc/src/lib.rs @@ -1,4 +1,24 @@ //! Types for communicating with niri via IPC. +//! +//! After connecting to the niri socket, you can send a single [`Request`] and receive a single +//! [`Reply`], which is a `Result` wrapping a [`Response`]. If you requested an event stream, you +//! can keep reading [`Event`]s from the socket after the response. +//! +//! You can use the [`socket::Socket`] helper if you're fine with blocking communication. However, +//! it is a fairly simple helper, so if you need async, or if you're using a different language, +//! you are encouraged to communicate with the socket manually. +//! +//! 1. Read the socket filesystem path from [`socket::SOCKET_PATH_ENV`] (`$NIRI_SOCKET`). +//! 2. Connect to the socket and write a JSON-formatted [`Request`] on a single line. You can follow +//! up with a line break and a flush, or just flush and shutdown the write end of the socket. +//! 3. Niri will respond with a single line JSON-formatted [`Reply`]. +//! 4. If you requested an event stream, niri will keep responding with JSON-formatted [`Event`]s, +//! on a single line each. +//! +//! ## Backwards compatibility +//! +//! This crate follows the niri version. It is **not** API-stable in terms of the Rust semver. In +//! particular, expect new struct fields and enum variants to be added in patch version bumps. #![warn(missing_docs)] use std::collections::HashMap; diff --git a/niri-ipc/src/state.rs b/niri-ipc/src/state.rs index 8d2d1744..2ab58fc3 100644 --- a/niri-ipc/src/state.rs +++ b/niri-ipc/src/state.rs @@ -1,4 +1,10 @@ //! Helpers for keeping track of the event stream state. +//! +//! 1. Create an [`EventStreamState`] using `Default::default()`, or any individual state part if +//! you only care about part of the state. +//! 2. Connect to the niri socket and request an event stream. +//! 3. Pass every [`Event`] to [`EventStreamStatePart::apply`] on your state. +//! 4. Read the fields of the state as needed. use std::collections::hash_map::Entry; use std::collections::HashMap; |