libei/doc/brei.dox.tmpl

/**

@page brei BREI - The Protocol for EI

BREI is the binary protocol used by libei and libeis to communicate with each other.
It is a **stable protocol** and may be used directly by e.g. language bindings.

The source for this protocol is [the protocol.xml file in the libei repository](https://gitlab.freedesktop.org/libinput/libei/-/blob/main/proto/protocol.xml).

The protocol consists of **Requests** - messages sent from the EI client to the
EIS implementation and **Events** - messages sent from the EIS implementation
to the client. Requests and Events are grouped into **Interfaces**.

All **Objects** created by EI or EIS have a unique object ID, each request
and event has a unique opcode. A message on the wire identifies the object
and the opcode which then allows the implementation to parse the
message according to the protocol specification.

The BREI protocol is modelled after the Wayland protocol.

@tableofcontents

@{

{% for interface in interfaces %}
\section {{interface.name}} {{interface.name}}

{% if interface.requests %}
<table>
<caption id="table-requests-{{interface.name}}">{{interface.name}} requests</caption>
<tr><th>Opcode</th><th>Request</th><th>Since</th><th>Summary</th></tr>
{% for request in interface.requests %}
<tr>
<td>{{request.opcode}}</td><td>@ref {{request.fqdn}} "{{request.name}}"</td><td>{{request.since}}</td><td>{{request.description.summary}}</td>
</tr>
{% endfor %}
</table>
{% endif %}

{% if interface.events %}
<table>
<caption id="table-events-{{interface.name}}">{{interface.name}} events</caption>
<tr><th>Opcode</th><th>event</th><th>Since</th><th>Summary</th></tr>
{% for event in interface.events %}
<tr>
<td>{{event.opcode}}</td><td>@ref {{event.fqdn}} "{{event.name}}"</td><td>{{event.since}}</td><td>{{event.description.summary}}</td>
</tr>
{% endfor %}
</table>
{% endif %}


{{interface.description.text}}

{% if interface.requests %}
@subsection {{interface.name}}_enums {{interface.name}} enums

{% for enum in interface.enums %}
@subsubsection {{enum.fqdn}} {{interface.name}}.{{enum.name}}
<strong>{{enum.description.summary}}</strong>

<table>
<caption id="table-{{enum.fqdn}}">{{interface.name}}.{{enum.name}}</caption>
<tr><th>Name</th><th>Value</th><th>Summary</th></tr>
{% for entry in enum.entries %}
<tr>
<td><strong>{{entry.name|upper()}}</strong></td><td>{{entry.value}}</td><td>{{entry.summary}}</td>
</tr>
{% endfor %}
</table>

{{enum.description.text}}

{% endfor %}
{% endif %}


{% if interface.requests %}
@subsection {{interface.name}}_requests {{interface.name}} requests


{% for request in interface.requests %}
@subsubsection {{request.fqdn}} {{interface.name}}.{{request.name}}

{% if request.arguments %}
<table>
<caption id="table-{{request.fqdn}}">Arguments</caption>
<tr><th>Name</th><th>Type</th><th>Summary</th></tr>
{% for arg in request.arguments %}
<tr>
<td><strong>{{arg.name}}</strong></td><td>{{arg.protocol_type}}</td><td>{{arg.summary}}</td>
</tr>
{% endfor %}
</table>
{% endif %}

{{request.description.text}}
{% endfor %}

{% endif %}

{% if interface.events %}
@subsection {{interface.name}}_events {{interface.name}} events

{% for event in interface.events %}
@subsubsection {{event.fqdn}} {{interface.name}}.{{event.name}}

{% if event.arguments %}
<table>
<caption id="table-{{event.fqdn}}">Arguments</caption>
<tr><th>Name</th><th>Type</th><th>Summary</th></tr>
{% for arg in event.arguments %}
<tr>
<td><strong>{{arg.name}}</strong></td><td>{{arg.protocol_type}}</td><td>{{arg.summary}}</td>
</tr>
{% endfor %}
</table>
{% endif %}

{{event.description.text}}
{% endfor %}

{% endif %}

{% endfor %}

@}

*/