nixo
/
gri3-wm
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

committed the wrong file

next
Michael Stapelberg 2010-03-12 03:06:40 +01:00
parent 520f4d15d2
commit 4cbece46c2
2 changed files with 146 additions and 766 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
docs/ipc Normal file
View File

@ -0,0 +1,146 @@
IPC interface (interprocess communication)
==========================================
Michael Stapelberg <michael+i3@stapelberg.de>
March 2010
This document describes how to interface with i3 from a separate process. This
is useful for example to remote-control i3 (to write test cases for example) or
to get various information like the current workspaces to implement an external
workspace bar.
The method of choice for IPC in our case is a unix socket because it has very
little overhead on both sides and is usually available without headaches in
most languages. In the default configuration file, no ipc-socket path is
specified and thus no socket is created. The standard path (which +i3-msg+ and
+i3-input+ use) is +/tmp/i3-ipc.sock+.
== Establishing a connection
To establish a connection, simply open the IPC socket. The following code
snippet illustrates this in Perl:
-------------------------------------------------------------
use IO::Socket::UNIX;
my $sock = IO::Socket::UNIX->new(Peer => '/tmp/i3-ipc.sock');
-------------------------------------------------------------
== Sending messages to i3
To send a message to i3, you have to format in the binary message format which
i3 expects. This format specifies a magic string in the beginning to ensure
the integrity of messages (to prevent follow-up errors). Afterwards follows
the length of the payload of the message as 32-bit integer and the type of
the message as 32-bit integer (the integers are not converted, so they are
in native byte order).
The magic string currently is "i3-ipc" and will only be changed when a change
in the IPC API is done which breaks compatibility (we hope that we don’t need
to do that).
Currently implemented message types are the following:
0 (COMMAND)::
The payload of the message is a command for i3 (like the commands you
can bind to keys in the configuration file) and will be executed
directly after receiving it. There is no reply to this message.
1 (GET_WORKSPACES)::
Gets the current workspaces. The reply will be a JSON-encoded list of
workspaces (see the reply section).
So, a typical message could look like this:
--------------------------------------------------
"i3-ipc" <message length> <message type> <payload>
--------------------------------------------------
Or, as a hexdump:
------------------------------------------------------------------------------
00000000 69 33 2d 69 70 63 04 00 00 00 00 00 00 00 65 78 |i3-ipc........ex|
00000010 69 74 0a |it.|
------------------------------------------------------------------------------
To generate and send such a message, you could use the following code in Perl:
------------------------------------------------------------
sub format_ipc_command {
my ($msg) = @_;
my $len;
# Get the real byte count (vs. amount of characters)
{ use bytes; $len = length($msg); }
return "i3-ipc" . pack("LL", $len, 0) . $msg;
}
$sock->write(format_ipc_command("exit"));
------------------------------------------------------------
== Receiving replies from i3
Replies of i3 usually consist of a simple string (the length of the string
is the message_length, so you can consider them length-prefixed) which in turn
contain the JSON serialization of a data structure. For example, the
GET_WORKSPACES message returns an array of workspaces (each workspace is a map
with certain attributes).
=== Reply format
The reply format is identical to the normal message format. There also is
the magic string, then the message length, then the message type and the
payload.
The following reply types are implemented:
1 (GET_WORKSPACES)::
Reply to the GET_WORKSPACES message.
=== GET_WORKSPACES reply
The reply consists of a serialized list of workspaces. Each workspace has the
following properties:
num (integer)::
The internal number of the workspace. Corresponds to the command
to switch to this workspace.
name (string)::
The name of this workspace (by default num+1), as changed by the
user. Encoded in UTF-8.
visible (boolean)::
Whether this workspace is currently visible on an output (multiple
workspaces can be visible at the same time).
focused (boolean)::
Whether this workspace currently has the focus (only one workspace
can have the focus at the same time).
rect (map)::
The rectangle of this workspace (equals the rect of the output it
is on), consists of x, y, width, height.
output (string)::
The video output this workspace is on (LVDS1, VGA1, …).
*Example:*
-------------------
[
{
"num": 0,
"name": "1",
"visible": true,
"focused": true,
"rect": {
"x": 0,
"y": 0,
"width": 1280,
"height": 800
},
"output": "LVDS1"
},
{
"num": 1,
"name": "2",
"visible": false,
"focused": false,
"rect": {
"x": 0,
"y": 0,
"width": 1280,
"height": 800
},
"output": "LVDS1"
}
]
-------------------

766
docs/ipc.html
View File

@ -1,766 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.5.2" />
<title>IPC interface (interprocess communication)</title>
<style type="text/css">
/* Debug borders */
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
/*
border: 1px solid red;
*/
}
body {
margin: 1em 5% 1em 5%;
}
a {
color: blue;
text-decoration: underline;
}
a:visited {
color: fuchsia;
}
em {
font-style: italic;
color: navy;
}
strong {
font-weight: bold;
color: #083194;
}
tt {
color: navy;
}
h1, h2, h3, h4, h5, h6 {
color: #527bbd;
font-family: sans-serif;
margin-top: 1.2em;
margin-bottom: 0.5em;
line-height: 1.3;
}
h1, h2, h3 {
border-bottom: 2px solid silver;
}
h2 {
padding-top: 0.5em;
}
h3 {
float: left;
}
h3 + * {
clear: left;
}
div.sectionbody {
font-family: serif;
margin-left: 0;
}
hr {
border: 1px solid silver;
}
p {
margin-top: 0.5em;
margin-bottom: 0.5em;
}
ul, ol, li > p {
margin-top: 0;
}
pre {
padding: 0;
margin: 0;
}
span#author {
color: #527bbd;
font-family: sans-serif;
font-weight: bold;
font-size: 1.1em;
}
span#email {
}
span#revnumber, span#revdate, span#revremark {
font-family: sans-serif;
}
div#footer {
font-family: sans-serif;
font-size: small;
border-top: 2px solid silver;
padding-top: 0.5em;
margin-top: 4.0em;
}
div#footer-text {
float: left;
padding-bottom: 0.5em;
}
div#footer-badges {
float: right;
padding-bottom: 0.5em;
}
div#preamble {
margin-top: 1.5em;
margin-bottom: 1.5em;
}
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
margin-top: 1.0em;
margin-bottom: 1.5em;
}
div.admonitionblock {
margin-top: 2.0em;
margin-bottom: 2.0em;
margin-right: 10%;
color: #606060;
}
div.content { /* Block element content. */
padding: 0;
}
/* Block element titles. */
div.title, caption.title {
color: #527bbd;
font-family: sans-serif;
font-weight: bold;
text-align: left;
margin-top: 1.0em;
margin-bottom: 0.5em;
}
div.title + * {
margin-top: 0;
}
td div.title:first-child {
margin-top: 0.0em;
}
div.content div.title:first-child {
margin-top: 0.0em;
}
div.content + div.title {
margin-top: 0.0em;
}
div.sidebarblock > div.content {
background: #ffffee;
border: 1px solid silver;
padding: 0.5em;
}
div.listingblock > div.content {
border: 1px solid silver;
background: #f4f4f4;
padding: 0.5em;
}
div.quoteblock, div.verseblock {
padding-left: 1.0em;
margin-left: 1.0em;
margin-right: 10%;
border-left: 5px solid #dddddd;
color: #777777;
}
div.quoteblock > div.attribution {
padding-top: 0.5em;
text-align: right;
}
div.verseblock > div.content {
white-space: pre;
}
div.verseblock > div.attribution {
padding-top: 0.75em;
text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
text-align: left;
}
div.admonitionblock .icon {
vertical-align: top;
font-size: 1.1em;
font-weight: bold;
text-decoration: underline;
color: #527bbd;
padding-right: 0.5em;
}
div.admonitionblock td.content {
padding-left: 0.5em;
border-left: 3px solid #dddddd;
}
div.exampleblock > div.content {
border-left: 3px solid #dddddd;
padding-left: 0.5em;
}
div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }
dl {
margin-top: 0.8em;
margin-bottom: 0.8em;
}
dt {
margin-top: 0.5em;
margin-bottom: 0;
font-style: normal;
color: navy;
}
dd > *:first-child {
margin-top: 0.1em;
}
ul, ol {
list-style-position: outside;
}
ol.arabic {
list-style-type: decimal;
}
ol.loweralpha {
list-style-type: lower-alpha;
}
ol.upperalpha {
list-style-type: upper-alpha;
}
ol.lowerroman {
list-style-type: lower-roman;
}
ol.upperroman {
list-style-type: upper-roman;
}
div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
margin-top: 0.1em;
margin-bottom: 0.1em;
}
div.tableblock > table {
border: 3px solid #527bbd;
}
thead, p.table.header {
font-family: sans-serif;
font-weight: bold;
}
tfoot {
font-weight: bold;
}
td > div.verse {
white-space: pre;
}
p.table {
margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
border-style: none;
}
div.tableblock > table[frame="hsides"] {
border-left-style: none;
border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
border-top-style: none;
border-bottom-style: none;
}
div.hdlist {
margin-top: 0.8em;
margin-bottom: 0.8em;
}
div.hdlist tr {
padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
font-weight: bold;
}
td.hdlist1 {
vertical-align: top;
font-style: normal;
padding-right: 0.8em;
color: navy;
}
td.hdlist2 {
vertical-align: top;
}
div.hdlist.compact tr {
margin: 0;
padding-bottom: 0;
}
.comment {
background: yellow;
}
.footnote, .footnoteref {
font-size: 0.8em;
}
span.footnote, span.footnoteref {
vertical-align: super;
}
#footnotes {
margin: 20px 0 20px 0;
padding: 7px 0 0 0;
}
#footnotes div.footnote {
margin: 0 0 5px 0;
}
#footnotes hr {
border: none;
border-top: 1px solid silver;
height: 1px;
text-align: left;
margin-left: 0;
width: 20%;
min-width: 100px;
}
@media print {
div#footer-badges { display: none; }
}
div#toc {
margin-bottom: 2.5em;
}
div#toctitle {
color: #527bbd;
font-family: sans-serif;
font-size: 1.1em;
font-weight: bold;
margin-top: 1.0em;
margin-bottom: 0.1em;
}
div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
margin-top: 0;
margin-bottom: 0;
}
div.toclevel2 {
margin-left: 2em;
font-size: 0.9em;
}
div.toclevel3 {
margin-left: 4em;
font-size: 0.9em;
}
div.toclevel4 {
margin-left: 6em;
font-size: 0.9em;
}
/* Workarounds for IE6's broken and incomplete CSS2. */
div.sidebar-content {
background: #ffffee;
border: 1px solid silver;
padding: 0.5em;
}
div.sidebar-title, div.image-title {
color: #527bbd;
font-family: sans-serif;
font-weight: bold;
margin-top: 0.0em;
margin-bottom: 0.5em;
}
div.listingblock div.content {
border: 1px solid silver;
background: #f4f4f4;
padding: 0.5em;
}
div.quoteblock-attribution {
padding-top: 0.5em;
text-align: right;
}
div.verseblock-content {
white-space: pre;
}
div.verseblock-attribution {
padding-top: 0.75em;
text-align: left;
}
div.exampleblock-content {
border-left: 3px solid #dddddd;
padding-left: 0.5em;
}
/* IE6 sets dynamically generated links as visited. */
div#toc a:visited { color: blue; }
</style>
<script type="text/javascript">
/*<![CDATA[*/
window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}
var asciidoc = { // Namespace.
/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////
/* Author: Mihai Bazon, September 2002
* http://students.infoiasi.ro/~mishoo
*
* Table Of Content generator
* Version: 0.4
*
* Feel free to use this script under the terms of the GNU General Public
* License, as long as you do not remove or alter this notice.
*/
/* modified by Troy D. Hanson, September 2006. License: GPL */
/* modified by Stuart Rackham, 2006, 2009. License: GPL */
// toclevels = 1..4.
toc: function (toclevels) {
function getText(el) {
var text = "";
for (var i = el.firstChild; i != null; i = i.nextSibling) {
if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
text += i.data;
else if (i.firstChild != null)
text += getText(i);
}
return text;
}
function TocEntry(el, text, toclevel) {
this.element = el;
this.text = text;
this.toclevel = toclevel;
}
function tocEntries(el, toclevels) {
var result = new Array;
var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
// Function that scans the DOM tree for header elements (the DOM2
// nodeIterator API would be a better technique but not supported by all
// browsers).
var iterate = function (el) {
for (var i = el.firstChild; i != null; i = i.nextSibling) {
if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
var mo = re.exec(i.tagName);
if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
}
iterate(i);
}
}
}
iterate(el);
return result;
}
var toc = document.getElementById("toc");
var entries = tocEntries(document.getElementById("content"), toclevels);
for (var i = 0; i < entries.length; ++i) {
var entry = entries[i];
if (entry.element.id == "")
entry.element.id = "_toc_" + i;
var a = document.createElement("a");
a.href = "#" + entry.element.id;
a.appendChild(document.createTextNode(entry.text));
var div = document.createElement("div");
div.appendChild(a);
div.className = "toclevel" + entry.toclevel;
toc.appendChild(div);
}
if (entries.length == 0)
toc.parentNode.removeChild(toc);
},
/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////
/* Based on footnote generation code from:
* http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
*/
footnotes: function () {
var cont = document.getElementById("content");
var noteholder = document.getElementById("footnotes");
var spans = cont.getElementsByTagName("span");
var refs = {};
var n = 0;
for (i=0; i<spans.length; i++) {
if (spans[i].className == "footnote") {
n++;
// Use [\s\S] in place of . so multi-line matches work.
// Because JavaScript has no s (dotall) regex flag.
note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
noteholder.innerHTML +=
"<div class='footnote' id='_footnote_" + n + "'>" +
"<a href='#_footnoteref_" + n + "' title='Return to text'>" +
n + "</a>. " + note + "</div>";
spans[i].innerHTML =
"[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
"' title='View footnote' class='footnote'>" + n + "</a>]";
var id =spans[i].getAttribute("id");
if (id != null) refs["#"+id] = n;
}
}
if (n == 0)
noteholder.parentNode.removeChild(noteholder);
else {
// Process footnoterefs.
for (i=0; i<spans.length; i++) {
if (spans[i].className == "footnoteref") {
var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
href = href.match(/#.*/)[0]; // Because IE return full URL.
n = refs[href];
spans[i].innerHTML =
"[<a href='#_footnote_" + n +
"' title='View footnote' class='footnote'>" + n + "</a>]";
}
}
}
}
}
/*]]>*/
</script>
</head>
<body>
<div id="header">
<h1>IPC interface (interprocess communication)</h1>
<span id="author">Michael Stapelberg</span><br />
<span id="email"><tt>&lt;<a href="mailto:michael+i3@stapelberg.de">michael+i3@stapelberg.de</a>&gt;</tt></span><br />
<span id="revdate">March 2010</span>
<div id="toc">
<div id="toctitle">Table of Contents</div>
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>This document describes how to interface with i3 from a separate process. This
is useful for example to remote-control i3 (to write test cases for example) or
to get various information like the current workspaces to implement an external
workspace bar.</p></div>
<div class="paragraph"><p>The method of choice for IPC in our case is a unix socket because it has very
little overhead on both sides and is usually available without headaches in
most languages. In the default configuration file, no ipc-socket path is
specified and thus no socket is created. The standard path (which <tt>i3-msg</tt> and
<tt>i3-input</tt> use) is <tt>/tmp/i3-ipc.sock</tt>.</p></div>
</div>
</div>
<h2 id="_establishing_a_connection">1. Establishing a connection</h2>
<div class="sectionbody">
<div class="paragraph"><p>To establish a connection, simply open the IPC socket. The following code
snippet illustrates this in Perl:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>use IO::Socket::UNIX;
my $sock = IO::Socket::UNIX-&gt;new(Peer =&gt; '/tmp/i3-ipc.sock');</tt></pre>
</div></div>
</div>
<h2 id="_sending_messages_to_i3">2. Sending messages to i3</h2>
<div class="sectionbody">
<div class="paragraph"><p>To send a message to i3, you have to format in the binary message format which
i3 expects. This format specifies a magic string in the beginning to ensure
the integrity of messages (to prevent follow-up errors). Afterwards follows
the length of the payload of the message as 32-bit integer and the type of
the message as 32-bit integer (the integers are not converted, so they are
in native byte order).</p></div>
<div class="paragraph"><p>The magic string currently is "i3-ipc" and will only be changed when a change
in the IPC API is done which breaks compatibility (we hope that we don’t need
to do that).</p></div>
<div class="paragraph"><p>Currently implemented message types are the following:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
0 (COMMAND)
</dt>
<dd>
<p>
The payload of the message is a command for i3 (like the commands you
can bind to keys in the configuration file) and will be executed
directly after receiving it. There is no reply to this message.
</p>
</dd>
<dt class="hdlist1">
1 (GET_WORKSPACES)
</dt>
<dd>
<p>
Gets the current workspaces. The reply will be a JSON-encoded list of
workspaces (see the reply section).
</p>
</dd>
</dl></div>
<div class="paragraph"><p>So, a typical message could look like this:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>"i3-ipc" &lt;message length&gt; &lt;message type&gt; &lt;payload&gt;</tt></pre>
</div></div>
<div class="paragraph"><p>Or, as a hexdump:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>00000000 69 33 2d 69 70 63 04 00 00 00 00 00 00 00 65 78 |i3-ipc........ex|
00000010 69 74 0a |it.|</tt></pre>
</div></div>
<div class="paragraph"><p>To generate and send such a message, you could use the following code in Perl:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>sub format_ipc_command {
my ($msg) = @_;
my $len;
# Get the real byte count (vs. amount of characters)
{ use bytes; $len = length($msg); }
return "i3-ipc" . pack("LL", $len, 0) . $msg;
}
$sock-&gt;write(format_ipc_command("exit"));</tt></pre>
</div></div>
</div>
<h2 id="_receiving_replies_from_i3">3. Receiving replies from i3</h2>
<div class="sectionbody">
<div class="paragraph"><p>Replies of i3 usually consist of a simple string (the length of the string
is the message_length, so you can consider them length-prefixed) which in turn
contain the JSON serialization of a data structure. For example, the
GET_WORKSPACES message returns an array of workspaces (each workspace is a map
with certain attributes).</p></div>
<h3 id="_reply_format">3.1. Reply format</h3><div style="clear:left"></div>
<div class="paragraph"><p>The reply format is identical to the normal message format. There also is
the magic string, then the message length, then the message type and the
payload.</p></div>
<div class="paragraph"><p>The following reply types are implemented:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
1 (GET_WORKSPACES)
</dt>
<dd>
<p>
Reply to the GET_WORKSPACES message.
</p>
</dd>
</dl></div>
<h3 id="_get_workspaces_reply">3.2. GET_WORKSPACES reply</h3><div style="clear:left"></div>
<div class="paragraph"><p>The reply consists of a serialized list of workspaces. Each workspace has the
following properties:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
num (integer)
</dt>
<dd>
<p>
The internal number of the workspace. Corresponds to the command
to switch to this workspace.
</p>
</dd>
<dt class="hdlist1">
name (string)
</dt>
<dd>
<p>
The name of this workspace (by default num+1), as changed by the
user. Encoded in UTF-8.
</p>
</dd>
<dt class="hdlist1">
visible (boolean)
</dt>
<dd>
<p>
Whether this workspace is currently visible on an output (multiple
workspaces can be visible at the same time).
</p>
</dd>
<dt class="hdlist1">
focused (boolean)
</dt>
<dd>
<p>
Whether this workspace currently has the focus (only one workspace
can have the focus at the same time).
</p>
</dd>
<dt class="hdlist1">
rect (map)
</dt>
<dd>
<p>
The rectangle of this workspace (equals the rect of the output it
is on), consists of x, y, width, height.
</p>
</dd>
<dt class="hdlist1">
output (string)
</dt>
<dd>
<p>
The video output this workspace is on (LVDS1, VGA1, …).
</p>
</dd>
</dl></div>
<div class="paragraph"><p><strong>Example:</strong></p></div>
<div class="listingblock">
<div class="content">
<pre><tt>[
{
"num": 0,
"name": "1",
"visible": true,
"focused": true,
"rect": {
"x": 0,
"y": 0,
"width": 1280,
"height": 800
},
"output": "LVDS1"
},
{
"num": 1,
"name": "2",
"visible": false,
"focused": false,
"rect": {
"x": 0,
"y": 0,
"width": 1280,
"height": 800
},
"output": "LVDS1"
}
]</tt></pre>
</div></div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated 2010-03-12 03:04:46 CEST
</div>
</div>
</body>
</html>