src/inc/varlink.htm


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

<!-- Generated file, you may edit and discard varlink.md :) -->
<p><a href="https://varlink.org" target="_blank">varlink</a> is a neat
little standard for doing debuggable IPC. It takes some of the nice
properties of DBUS, like the introspection capabilities, and combines
them with simple standard tools/technologies in the form of unix sockets
and JSON.</p>
<p>For C, there is a library by <a href="https://emersion.fr"
target="_blank">emersion</a> called vali, which does pretty much
everything all you need to get going:<br />
<a href="https://emersion.fr/blog/2025/announcing-vali/" class="uri"
target="_blank">https://emersion.fr/blog/2025/announcing-vali/</a></p>
<p>When you have written your service, here is how to interact with it
just using standard utils, socat and jq:</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="fu">cat</span> <span class="op">&lt;&lt;-EOF</span> <span class="kw">|</span> <span class="ex">jq</span> <span class="at">--raw-output0</span> <span class="kw">|</span> <span class="ex">socat</span> STDIO UNIX-CONNECT:<span class="st">&quot;</span><span class="va">$SOCKET</span><span class="st">&quot;</span> <span class="kw">|</span> <span class="ex">jq</span></span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="st">    {</span></span>
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="st">        &quot;method&quot;: &quot;org.varlink.service.GetInfo&quot;,</span></span>
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a><span class="st">    }</span></span>
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a><span class="op">EOF</span></span></code></pre></div>
<p>This is equivalent to using the varlink cli tool and running:
<code>varlink info $SOCKET</code></p>
<div class="sourceCode" id="cb2"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="fu">cat</span> <span class="op">&lt;&lt;-EOF</span> <span class="kw">|</span> <span class="ex">jq</span> <span class="at">--raw-output0</span> <span class="kw">|</span> <span class="ex">socat</span> STDIO UNIX-CONNECT:<span class="st">&quot;</span><span class="va">$SOCKET</span><span class="st">&quot;</span> <span class="kw">|</span> <span class="ex">jq</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="st">    {</span></span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a><span class="st">        &quot;method&quot;: &quot;org.varlink.service.GetInterfaceDescription&quot;,</span></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="st">        &quot;parameters&quot;: {</span></span>
<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a><span class="st">            &quot;interface&quot;: &quot;com.example.Foobar&quot;</span></span>
<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a><span class="st">        }</span></span>
<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a><span class="st">    }</span></span>
<span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a><span class="op">EOF</span></span></code></pre></div>
<p>This will return the service interface, if the service listening at
the socket actually implements it.</p>
<p>Note the use of <code>jq --raw-output0</code>. It is possible to omit
the jq invocations, the input JSON data should be followed by a NUL
byte.</p>