Crate async_i3ipc

async-i3ipc

This crate provides types and functions for working with i3's IPC protocol in an async context and with async-std (tokio version here). It re-exports the subcrate i3ipc-types because it is also used for a synchronous implementation of the protocol.

This library follows a similar API to the synchronous version. All important functions live on the I3 type. You must first await a connect call, then you can execute commands, send/read messages from i3, or subscribe to listen to Events.

Subscribe & Listen

use std::io;
use async_i3ipc::{
    event::{Event, Subscribe},
    I3,
};

#[async_std::main]
async fn main() -> io::Result<()> {
    let mut i3 = I3::connect().await?;
    let resp = i3.subscribe([Subscribe::Window]).await?;

    println!("{:#?}", resp);
    let mut listener = i3.listen();
    while let Ok(event) = listener.next().await {
        match event {
            Event::Workspace(ev) => println!("workspace change event {:?}", ev),
            Event::Window(ev) => println!("window event {:?}", ev),
            Event::Output(ev) => println!("output event {:?}", ev),
            Event::Mode(ev) => println!("mode event {:?}", ev),
            Event::BarConfig(ev) => println!("bar config update {:?}", ev),
            Event::Binding(ev) => println!("binding event {:?}", ev),
            Event::Shutdown(ev) => println!("shutdown event {:?}", ev),
            Event::Tick(ev) => println!("tick event {:?}", ev),
        }
    }
    Ok(())
}

Sending/Reading from I3

To send messages to i3, call any of the get_* functions on I3.

use std::io;
use async_i3ipc::{reply, I3};

#[async_std::main]
async fn main() -> io::Result<()> {
    let mut i3 = I3::connect().await?;
    // this type can be inferred, here is written explicitly:
    let tree: reply::Node = i3.get_tree().await?;
    println!("{:#?}", tree);

    Ok(())
}

All the get_* functions on I3 are simple wrappers around two main async functions. You could write any of them yourself, in fact:

use async_i3ipc::{msg, reply, MsgResponse, I3};

#[async_std::main]
let mut i3 = I3::connect().await?;
// send msg RunCommand with a payload
let payload = "some_command";
i3.send_msg_body(msg::Msg::RunCommand, payload).await?;
let resp: MsgResponse<Vec<reply::Success>> = i3.read_msg().await?;

Re-exports

pub use stream::EventStream;

Modules

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.
msg	For sending messages to i3
reply	Contains structs for deserializing messages from i3
stream

Structs

I3	Newtype wrapper for UnixStream that implements i3's IPC
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

Connect	Types implementing this are provided a connect function and return a stream
I3IPC	Trait containing methods to encode and decode message from i3
I3Protocol

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