Crate tokio_i3ipc

tokio-i3ipc

This crate provides types and functions for working with i3's IPC protocol within tokio. It re-exports the subcrate i3ipc-types because it is also used for a synchronous version of the code.

There are many ways you can interact with this library. You can import an already written future and simply spawn/run it, or you can use the building blocks to construct your own futures.

Subscribing

use tokio_i3ipc::{subscribe, event::{self, Subscribe}};

fn main() -> io::Result<()> {
    let mut rt =
        tokio::runtime::current_thread::Runtime::new().expect("Failed building runtime");
    // create a channel to receive responses
    let (tx, rx) = mpsc::channel(5);
    // pass a handle and `Sender` to `subscribe`
    subscribe(rt.handle(), tx, vec![Subscribe::Window])?;
    // handle the events received on the channel
    let fut = rx.for_each(|e: event::Event| {
        println!("received");
        println!("{:#?}", e);
        future::ok(())
    });
    rt.spawn(fut);
    rt.run().expect("failed runtime");
    Ok(())
}

send_msg, write_msg_json and write_msg will handle writing to i3. read_msg and read_msg_and will handle reading. The latter returns the stream again to continue using it.

Sending Messages to i3

To send messages to i3, there are a number of convenience futures that need only be passed a UnixStream and then run in your event loop.

use tokio_i3ipc::{I3, Connect, MsgResponse, get, reply};

fn main() {
    let fut = I3::connect()
        .expect("unable to get socket")
        .and_then(get::get_workspaces)
        .and_then(
            |(_stream, reply): (UnixStream, MsgResponse<reply::Workspaces>)| {
                // do something w/ reply::Workspaces
                futures::future::ok(())
            },
        )
        .map(|_| ())
        .map_err(|_| ());
    tokio::run(fut);
}

Modules

codec	Implements tokio_codec's Decoder trait to read event::Event from i3. Used for subscribe
event	For subscribing and receiving events, each struct matches a particular Subscribe variant. For instance, subscribing with Subscribe::Workspace will net Event::Workspace when workspace events are sent over the ipc.
get	Convenience functions for getting data from i3. All of the following functions take a UnixStream and return a Future that will produce some data. They are mappings of send_msg and read_msg_and their appropriate output.
io	Collection of functions & types implementing Future for interacting with the raw i3 stream
msg	For sending messages to i3
reply	Contains structs for deserializing messages from i3

Structs

I3	Newtype wrapper for ConnectFuture meant to resolve some Stream, mostly likely UnixStream
MsgResponse	Instead of returning an enum, we're returning a struct containing the Msg type and some body. An advantage to this over the enum method is that there is no minimum memory size that we must have. This is helpful when some variants are very large compared to others, as in the case of say reply::Node vs reply::Config

Constants

MAGIC

Traits

AsyncI3IPC	I3IPC provides default implementations for reading/writing buffers into a format i3 understands. This trait expresses that + asynchronousity
Connect	Types implementing this are provided a connect function and return a stream
Connect
I3IPC	Trait containing methods to encode and decode message from i3

Functions

decode_event	Given an event type and payload this function will deserialize the proper struct
decode_event_future	Decode a response into an Event
decode_msg	Decode a response into a MsgResponse
decode_response	Convenience function that decodes a single response and passes the type and undecoded buffer to a closure
socket_path	get socket path from i3
subscribe	An easy-to-use subscribe, all you need to do is pass a runtime handle and a Sender half of a channel, then listen on the rx side for events
subscribe_future	Function returns a Future that will send a Subscribe to i3 along with the events to listen to. Is bounded by AsyncI3IPC but you should almost always use UnixStream