i3ipc

package
v0.0.0-...-8c9ae4a Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 1, 2025 License: BSD-3-Clause Imports: 11 Imported by: 3

Documentation

Overview

i3ipc provides porcelain and primitive interfaces to write an integration with I3 or Sway via the IPC protocol defined.

Index

Constants

View Source 
const (
	UnknownSocketPathSource      SocketPathSource = iota // when a socket path cannot be found
	UserProvidedPathSource                               // socket path provided by user
	I3EnvironmentVarPathSource                           // socket path found in I3SOCK environment variable
	SwayEnvironmentVarPathSource                         // socket path found in SWAYSOCK environment variable
	I3ExecutableSource                                   // socket path found by calling i3 --get-socketpath
	SwayExecutableSource                                 // socket path found by calling sway --get-socketpath

	SwaySockEnvironmentVariable string = "SWAYSOCK"         // sway socket path environment variable name
	I3SockEnvironmentVariable   string = "I3SOCK"           // i3 socket path environment variable name
	SwayExecutableName          string = "sway"             // sway executable name
	I3ExecutableName            string = "i3"               // i3 executable name
	SocketPathExecutableFlag    string = "--get-socketpath" // sway/i3 socket path flag
)

Variables

View Source 
var (
	// ErrNoExecutablesFound is returned when socket path resolution has
	// fallen back to using either a sway or i3 executable to find the IPC
	// socket path but no executable can be located on the PATH
	ErrNoExecutablesFound *SocketPathError = &SocketPathError{"no sway or i3 executables found on path", []error{}}
	// ErrConnectionAlreadyClosed is returned when a connection has already
	// been closed but a request has been made to the connection regardless.
	ErrConnectionAlreadyClosed *ConnectionError = &ConnectionError{"connection to IPC socket is already closed", []error{}}
	// ErrEventTypeHandlerAlreadyRegistered is returned when an
	// [EventSubscriber] has an [EventHandler] already registered for a given
	// [messages.EventType]
	ErrEventTypeHandlerAlreadyRegistered *ClientError = &ClientError{"handler already registered for event type", []error{}}
	// ErrEmptyBarID is returne dwhen [Client.GetBarConfig] is called with an
	// empty string for the bar ID.
	ErrEmptyBarID *ClientError = &ClientError{AdditionalContext: "a request for bar configuration was made with an empty id, to get the list of bar IDs, use GetBarIDs instead", Errors: []error{}}
)

Functions

This section is empty.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a level of porcelain around a Connection and the various message types supported by i3ipc.

func NewClient 

func NewClient(ctx context.Context) (*Client, error)

NewClient creates a new Client by inspecting environment variables for the Unix IPC socket path or using binaries found in the PATH to determine the Unix IPC socket path. If it cannot find a path via either the environment variables or binaries in the PATH, it returns an error. If it cannot open a connection to the given path it returns an error.

func NewClientFromPath 

func NewClientFromPath(ctx context.Context, path string) (*Client, error)

NewClientFromPath allows the user to provide the path to the Unix IPC socket without inspecting environment variables or executing binaries on the system.

func NewClientFromSocketPath 

func NewClientFromSocketPath(ctx context.Context, sp SocketPath) (*Client, error)

NewClientFromSocketPath allows users to directly specify a SocketPath to use to create a new client. This function is used by both NewClient and NewClientFromPath to create the final Client as well.

func (*Client) Close 

func (c *Client) Close() error

func (*Client) Do 

func (c *Client) Do(ctx context.Context, mr messages.RequestMessager) (messages.ReplyMessage, error)

Do allows a user to specify a specific IPC request message (e.g., pkg/i3ipc/messages.RunCommandRequest, pkg/i3ipc/messages.GetWorkspacesRequest) without using the convenience methods below.

func (*Client) GetBarConfig 

func (c *Client) GetBarConfig(ctx context.Context, barID string) (messages.BarConfigReply, error)

GetBarConfig retrieves the specified bar's configuration using the bar's ID. This is achieved by sending a GET_BAR_CONFIG (messages.GetBarConfigRequestType) message with the id as the payload.

func (*Client) GetBarIDs 

func (c *Client) GetBarIDs(ctx context.Context) ([]string, error)

GetBarIDs retrieves the list of bar identifiers. This is achieved by sending a GET_BAR_CONFIG (messages.GetBarConfigRequestType) message without a payload.

func (*Client) GetBindingModes 

func (c *Client) GetBindingModes(ctx context.Context) ([]string, error)

GetBindingModes retrieve the list of binding modes that currently configured. It returns a slice of strings

func (*Client) GetBindingState 

func (c *Client) GetBindingState(ctx context.Context) (string, error)

func (*Client) GetConfig 

func (c *Client) GetConfig(ctx context.Context) (string, error)

func (*Client) GetInputs 

func (c *Client) GetInputs(ctx context.Context) (messages.InputReplies, error)

func (*Client) GetMarks 

func (c *Client) GetMarks(ctx context.Context) ([]string, error)

GetMarks retrieves the list of currently set marks

func (*Client) GetOutputs 

func (c *Client) GetOutputs(ctx context.Context) (messages.OutputsReplies, error)

GetOutputs retrieves the list of current outputs

func (*Client) GetSeats 

func (c *Client) GetSeats(ctx context.Context) (messages.SeatReplies, error)

func (*Client) GetTree 

func (c *Client) GetTree(ctx context.Context) (messages.TreeReply, error)

GetTree retrieves the node layout tree

func (*Client) GetVersion 

func (c *Client) GetVersion(ctx context.Context) (messages.VersionReply, error)

GetVersion retrieves the version information about the i3 or sway process. This is achieved by sending a GET_VERSION (messages.GetVersionRequestType) message.

func (*Client) GetWorkspaces 

func (c *Client) GetWorkspaces(ctx context.Context) (messages.WorkspaceReplies, error)

GetWorkspaces retrieves the list of current workspaces known by the window manager. It takes no parameters beyond a context.Context as there are no parameters to a GET_WORKSPACES IPC call.

func (*Client) RunCommand 

func (c *Client) RunCommand(ctx context.Context, command string) (messages.CommandReplies, error)

RunCommand accepts a string for a i3ipc command to run. See https://i3wm.org/docs/userguide.html#list_of_commands for the list of commands that can be run via IPC.

func (*Client) SendTick 

func (c *Client) SendTick(ctx context.Context) (bool, error)

func (*Client) Subscriber 

func (c *Client) Subscriber(ctx context.Context) (EventSubscriber, error)

Subscriber creates a new EventSubscriber with a distinct IPC Connection to allow the existing Client to continue to work while using the new connection to listen for events

func (*Client) Sync 

func (c *Client) Sync(ctx context.Context) (bool, error)

type ClientError 

type ClientError struct {
	AdditionalContext string
	Errors            []error
}

func (ClientError) Error 

func (e ClientError) Error() string

func (ClientError) Unwrap 

func (e ClientError) Unwrap() []error

type Connection 

type Connection struct {
	// contains filtered or unexported fields
}

Connection maintains the actual connection to the unix socket for managing i3 interprocess communication

func NewConnection 

func NewConnection(sp SocketPath) (*Connection, error)

NewConnection uses a resolved SocketPath and creates a connection to the socket. If there is an issue opening the IPC socket, it will return a ConnectionError

func (*Connection) Close 

func (c *Connection) Close() error

Close attempts to close an IPC connection. If the connection is already closed, it will return ErrConnectionAlreadyClosed. If there's an error closing the connection it will return a ConnectionError

func (*Connection) Do 

func (c *Connection) Do(ctx context.Context, request messages.RequestMessage) (messages.ReplyMessage, error)

Do sends the prepared request to the remote via the IPC connection. If there is an error, it will return an empty messages.ReplyMessage and a ConnectionError

func (*Connection) IsOpen 

func (c *Connection) IsOpen() bool

IsOpen returns a bool that indicates if the connection is presently still open or of it is closed.

func (*Connection) Read 

func (c *Connection) Read(ctx context.Context) (messages.ReplyMessage, error)

Read simply reads from the connection and parses the reply from the IPC server to a messages.ReplyMessage

type ConnectionError 

type ConnectionError struct {
	AdditionalContext string
	Errors            []error
}

ConnectionError provides structure for any errors returned by a Connection

func (ConnectionError) Error 

func (e ConnectionError) Error() string

func (ConnectionError) Unwrap 

func (e ConnectionError) Unwrap() []error

type EventHandler 

type EventHandler interface {
	Handle(messages.ReplyMessage)
}

type EventHandlerFunc 

type EventHandlerFunc func(messages.ReplyMessage)

func (EventHandlerFunc) Handle 

func (f EventHandlerFunc) Handle(m messages.ReplyMessage)

type EventSubscriber 

type EventSubscriber interface {
	SubscribedTo() []messages.ReplyMessageType
	SetHandler(messages.ReplyMessageType, EventHandler) error
	RemoveHandler(messages.ReplyMessageType)
	Start(context.Context) error
	Listen(context.Context) error
	Close() error
}

type IPCCommunicator 

type IPCCommunicator interface {
	Do(context.Context, messages.RequestMessage) (messages.ReplyMessage, error)
	Read(context.Context) (messages.ReplyMessage, error)
}

IPCCommunicator is an interface to specify the Do and Read methods on a Connection for dependency injection. Do in IPCCommunicator is different from PorcelainClient's Do

type PorcelainClient 

type PorcelainClient interface {
	PorcelainDoer
	RunCommand(context.Context, string) (messages.CommandReplies, error)
	GetWorkspaces(context.Context) (messages.WorkspaceReplies, error)
	GetOutputs(context.Context) (messages.OutputsReplies, error)
	GetTree(context.Context) (messages.TreeReply, error)
	GetMarks(context.Context) ([]string, error)
	GetBarIDs(context.Context) ([]string, error)
	GetBarConfig(context.Context, string) (messages.BarConfigReply, error)
	GetVersion(context.Context) (messages.VersionReply, error)
	GetBindingModes(context.Context) ([]string, error)
	GetConfig(context.Context) (string, error)
	SendTick(context.Context) (bool, error)
	Sync(context.Context) (bool, error)
	GetBindingState(context.Context) (string, error)
	GetInputs(context.Context) (messages.InputReplies, error)
	Subscriber(context.Context) (EventSubscriber, error)
}

PorcelainClient defines the interface for the methods that are akin to the porcelain on the client for working with the IPC client.

type PorcelainDoer 

type PorcelainDoer interface {
	Do(context.Context, messages.RequestMessager) (messages.ReplyMessage, error)
}

PorcelainDoer allows one to satisfy the Do interface for a PorcelainClient

type SocketPath 

type SocketPath struct {
	Path   string
	Source SocketPathSource
}

SocketPath is the path to the unix socket on the system to communicate with. It includes the source so determining how the path was discovered can be debugged more easily.

func FindSocketPath 

func FindSocketPath(ctx context.Context) (SocketPath, error)

FindSocketPath looks at environment variables to find a path to the IPC socket and otherwise falls back to calling the sway and/or i3 executables in one's PATH to find it.

type SocketPathError 

type SocketPathError struct {
	AdditionalContext string
	Errors            []error
}

SocketPathError provides structure for any errors returned during socket path resolution, namely from calling FindSocketPath

func (SocketPathError) Error 

func (e SocketPathError) Error() string

func (SocketPathError) Unwrap 

func (e SocketPathError) Unwrap() []error

type SocketPathSource 

type SocketPathSource uint32

SocketPathSource tags how the library found the socket path to talk to SwayWM and I3

func (SocketPathSource) String 

func (s SocketPathSource) String() string

String provides a human readable explanation of where the socket path was found

type SubscriptionClient 

type SubscriptionClient struct {
	// contains filtered or unexported fields
}

SubscriptionClient manages subscriptions to event types

func (*SubscriptionClient) Close 

func (c *SubscriptionClient) Close() error

func (*SubscriptionClient) Listen 

func (c *SubscriptionClient) Listen(ctx context.Context) error

func (*SubscriptionClient) RemoveHandler 

func (c *SubscriptionClient) RemoveHandler(et messages.ReplyMessageType)

func (*SubscriptionClient) SetHandler 

func (c *SubscriptionClient) SetHandler(et messages.ReplyMessageType, h EventHandler) error

func (*SubscriptionClient) Start 

func (c *SubscriptionClient) Start(ctx context.Context) error

func (*SubscriptionClient) SubscribedTo 

func (c *SubscriptionClient) SubscribedTo() []messages.ReplyMessageType

Source Files

View all Source files

Directories

Path Synopsis
messages provides types and data to encapsulate the protocol described in https://i3wm.org/docs/ipc.html#_sending_messages_to_i3
 messages provides types and data to encapsulate the protocol described in https://i3wm.org/docs/ipc.html#_sending_messages_to_i3
subscriptions provides some porcelain functions for managing subscription handlers when using pkg/i3ipc.EventSubscriber
 subscriptions provides some porcelain functions for managing subscription handlers when using pkg/i3ipc.EventSubscriber

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.