Class: I3Ipc::Protocol

Inherits:
Object
  • Object
show all
Defined in:
lib/i3ipc/protocol.rb

Overview

Communication interface with i3-ipc. Can connect to i3-ipc socket, disconnect, send and receive messages.

For i3-ipc interface details refer to https://i3wm.org/docs/ipc.html.

Examples:

protocol = Protocol.new
protocol.send(7)
puts protocol.receive
protocol.disconnect

Defined Under Namespace

Classes: NotConnected, WrongMagicString, WrongType

Constant Summary collapse

MAGIC_STRING =

Magic string for i3-ipc protocol to ensure the integrity of messages.

'i3-ipc'

Instance Method Summary collapse

Constructor Details

#initialize(socketpath = nil) ⇒ Protocol

Returns a new instance of Protocol.



48
49
50
 
# File 'lib/i3ipc/protocol.rb', line 48

def initialize(socketpath = nil)
  @socketpath = socketpath ? socketpath : get_socketpath
end

Instance Method Details

#connect ⇒ Object

Connects to i3-ipc server socket using UNIXSocket. Does nothing if already connected.



54
55
56
 
# File 'lib/i3ipc/protocol.rb', line 54

def connect
  @socket = UNIXSocket.new(@socketpath) unless @socket
end

#disconnect ⇒ Object

Disconnects from i3-ipc server socket. Does nothing if not connected.



60
61
62
63
 
# File 'lib/i3ipc/protocol.rb', line 60

def disconnect
  @socket && @socket.close
  @socket = nil
end

#receive(type = nil) ⇒ String

Receives message from i3-ipc server socket.

Parameters:

  • type (Integer) (defaults to: nil) —

    expected type of the message.

Returns:

  • (String) —

    unpacked response from i3 server.

Raises:



84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/i3ipc/protocol.rb', line 84

def receive(type = nil)
  check_connected
  # length of "i3-ipc" + 4 bytes length + 4 bytes type
  data = @socket.read 14
  magic, len, recv_type = unpack_header(data)

  raise WrongMagicString.new(magic) unless MAGIC_STRING.eql? magic
  type && (raise WrongType.new(type, recv_type) unless type == recv_type)

  @socket.read(len)
end

#receive_event(type = nil) ⇒ String

Receives event from i3-ipc server socket.

Parameters:

  • type (Integer) (defaults to: nil) —

    expected type of the message.

Returns:

  • (String) —

    unpacked response from i3 server.

Raises:



105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/i3ipc/protocol.rb', line 105

def receive_event(type = nil)
  check_connected
  # length of "i3-ipc" + 4 bytes length + 4 bytes type
  data = @socket.read 14
  magic, len, recv_type = unpack_header(data)

  # Strip highest bit
  recv_type = recv_type & 2147483647

  raise WrongMagicString.new(magic) unless MAGIC_STRING.eql? magic
  type && (raise WrongType.new(type, recv_type) unless type == recv_type)

  @socket.read(len)
end

#send(type, payload = nil) ⇒ Object

Sends packed message to i3-ipc server socket.

Parameters:

  • type (Integer) —

    type of the message.

  • payload (String) (defaults to: nil) —

    message payload.

Raises:



70
71
72
73
 
# File 'lib/i3ipc/protocol.rb', line 70

def send(type, payload = nil)
  check_connected
  @socket.write(pack(type, payload))
end