mirrors/wayland
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wayland/wayland.git synced 2025-10-29 05:40:16 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: document the enum and bitfield attributes

Browse source 
Introduce the enum and bitfield attributes, which allow you to refer to the enum
you are expecting in an argument, and specify which enums are to be thought of
as bitfields.

Changes since v3:
 - Fix typo ("description" -> "descriptive")

Signed-off-by: Auke Booij <auke@tulcod.com>
Reviewed-by: Nils Chr. Brause <nilschrbrause@googlemail.com>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
This commit is contained in:
Auke Booij 2015-10-26 12:16:31 +00:00 • committed by Bryce Harrington
parent f150d7aec2
commit 999225c17a
1 changed files with 35 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

41
doc/publican/sources/Protocol.xml
View file

@ -14,6 +14,38 @@
object implements an interface and the requests include an opcode that
identifies which method in the interface to invoke.
</para>
<para>
The protocol is message-based. A message sent by a client to the server
is called request. A message from the server to a client is called event.
A message has a number of arguments, each of which has a certain type (see
<xref linkend="sect-Protocol-Wire-Format"/> for a list of argument types).
</para>
<para>
Additionally, the protocol can specify <type>enum</type>s which associate
names to specific numeric enumeration values. These are primarily just
descriptive in nature: at the wire format level enums are just integers.
But they also serve a secondary purpose to enhance type safety or
otherwise add context for use in language bindings or other such code.
This latter usage is only supported so long as code written before these
attributes were introduced still works after; in other words, adding an
enum should not break API, otherwise it puts backwards compatibility at
risk.
</para>
<para>
<type>enum</type>s can be defined as just a set of integers, or as
bitfields. This is specified via the <type>bitfield</type> boolean
attribute in the <type>enum</type> definition. If this attribute is true,
the enum is intended to be accessed primarily using bitwise operations,
for example when arbitrarily many choices of the enum can be ORed
together; if it is false, or the attribute is omitted, then the enum
arguments are a just a sequence of numerical values.
</para>
<para>
The <type>enum</type> attribute can be used on either <type>uint</type>
or <type>int</type> arguments, however if the <type>enum</type> is
defined as a <type>bitfield</type>, it can only be used on
<type>uint</type> args.
</para>
<para>
The server sends back events to the client, each event is emitted from
an object. Events can be error conditions. The event includes the
@ -62,14 +94,11 @@
The protocol is sent over a UNIX domain stream socket, where the endpoint
usually is named <systemitem class="service">wayland-0</systemitem>
(although it can be changed via <emphasis>WAYLAND_DISPLAY</emphasis>
in the environment). The protocol is message-based. A
message sent by a client to the server is called request. A message
from the server to a client is called event. Every message is
structured as 32-bit words, values are represented in the host's
byte-order.
in the environment).
</para>
<para>
The message header has 2 words in it:
Every message is structured as 32-bit words; values are represented in the
host's byte-order. The message header has 2 words in it:
<itemizedlist>
<listitem>
<para>