Document unusual wl_registry.bind new_id behavior

When wayland-scanner encounters a new_id field with no corresponding
interface name defined, instead of emitting a function whose signature
lines up with the usual case (a uint32_t ID), it adds the interface name
as a string and the version number so that the interface can be
identified from the protcol message.

Without docs, this was previously left for the interprid wire protocol
implementor (e.g. me an hour ago) to discover when Wayland clients send
them apparently bogus messages.

I would have preferred if a different primitive type were used here
(e.g. typed_new_id) to reflect the fact that the wire protocol is
different, but I felt it unwise to add a new primitive to wayland.xml in
$current_year.
This commit is contained in:
Drew DeVault 2019-07-29 22:39:00 -04:00
parent 493ab79bd2
commit a2f1343b7e

View file

@ -167,10 +167,10 @@
<term>new_id</term>
<listitem>
<para>
The 32-bit object ID. On requests, the client
decides the ID. The only events with <type>new_id</type> are
advertisements of globals, and the server will use IDs below
0x10000.
The 32-bit object ID. Generally, the interface used for the new
object is inferred from the xml, but in the case where it's not
specified, a new_id is preceeded by a <code>string</code> specifying
the interface name, and a <code>uint</code> specifying the version.
</para>
</listitem>
</varlistentry>