On Thu, Oct 27, 2016 at 08:55:01AM -0700, Yong Bakos wrote: > From: Yong Bakos <[email protected]> > > Signed-off-by: Yong Bakos <[email protected]>
excellent, very informative! Reviewed-by: Peter Hutterer <[email protected]> Cheers, Peter > --- > src/wayland-util.h | 68 > ++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 68 insertions(+) > > diff --git a/src/wayland-util.h b/src/wayland-util.h > index 7b280d1..4dba1ed 100644 > --- a/src/wayland-util.h > +++ b/src/wayland-util.h > @@ -68,9 +68,77 @@ extern "C" { > #define WL_PRINTF(x, y) > #endif > > +/** > + * Protocol message signature > + * > + * A wl_message describes the signature of an actual protocol message, such > as a > + * request or event, that adheres to the Wayland protocol wire format. The > + * protocol implementation uses a wl_message within its demarshal machinery > for > + * decoding messages between a compositor and its clients. In a sense, a > + * wl_message is to a protocol message like a class is to an object. > + * > + * The `name` of a wl_message is the name of the corresponding protocol > message. > + * The `signature` is an ordered list of symbols representing the data types > + * of message arguments and, optionally, a protocol version and indicators > for > + * nullability. A leading integer in the `signature` indicates the _since_ > + * version of the protocol message. A `?` preceding a data type symbol > indicates > + * that the following argument type is nullable. When no arguments accompany > a > + * message, `signature` is an empty string. > + * > + * * `i`: int > + * * `u`: uint > + * * `f`: fixed > + * * `s`: string > + * * `o`: object > + * * `n`: new_id > + * * `a`: array > + * * `h`: fd > + * * `?`: following argument is nullable > + * > + * While demarshaling primitive arguments is straightforward, when > demarshaling > + * messages containing `object` or `new_id` arguments, the protocol > + * implementation often must determine the type of the object. The `types` > of a > + * wl_message is an array of wl_interface references that correspond to `o` > and > + * `n` arguments in `signature`, with `NULL` placeholders for arguments with > + * non-object types. > + * > + * Consider the protocol event wl_display `delete_id` that has a single > `uint` > + * argument. The wl_message is: > + * > + * \code > + * { "delete_id", "u", [NULL] } > + * \endcode > + * > + * Here, the message `name` is `"delete_id"`, the `signature` is `"u"`, and > the > + * argument `types` is `[NULL]`, indicating that the `uint` argument has no > + * corresponding wl_interface since it is a primitive argument. > + * > + * In contrast, consider a `wl_foo` interface supporting protocol request > `bar` > + * that has existed since version 2, and has two arguments: a `uint` and an > + * object of type `wl_baz_interface` that may be `NULL`. Such a `wl_message` > + * might be: > + * > + * \code > + * { "bar", "2u?o", [NULL, &wl_baz_interface] } > + * \endcode > + * > + * Here, the message `name` is `"bar"`, and the `signature` is `"2u?o"`. > Notice > + * how the `2` indicates the protocol version, the `u` indicates the first > + * argument type is `uint`, and the `?o` indicates that the second argument > + * is an object that may be `NULL`. Lastly, the argument `types` array > indicates > + * that no wl_interface corresponds to the first argument, while the type > + * `wl_baz_interface` corresponds to the second argument. > + * > + * \sa wl_argument > + * \sa wl_interface > + * \sa <a > href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Wire-Format";>Wire > Format</a> > + */ > struct wl_message { > + /** Message name */ > const char *name; > + /** Message signature */ > const char *signature; > + /** Object argument interfaces */ > const struct wl_interface **types; > }; > > -- > 2.7.2 > > _______________________________________________ > wayland-devel mailing list > [email protected] > https://lists.freedesktop.org/mailman/listinfo/wayland-devel > _______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
